diff --git a/README.md b/README.md
index d446778..cf9ba43 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,132 @@
 # gemini-rs [![Rust](https://github.com/andreban/gemini-rs/actions/workflows/rust.yml/badge.svg)](https://github.com/andreban/gemini-rs/actions/workflows/rust.yml)
-A Rust wrapper for the Google Cloud Gemini REST API
+
+A Rust wrapper for the Google Cloud Gemini REST API (Vertex AI).
+
+## Features
+
+- **Text Generation**: Generate text responses from Gemini models
+- **Streaming**: Stream responses in real-time using SSE
+- **Text Embeddings**: Generate text embeddings for ML pipelines
+- **Token Counting**: Count tokens before making API calls
+- **Image Generation**: Generate and predict images
+- **Conversations**: Maintain multi-turn dialogue context
+- **Safety Settings**: Configure content safety thresholds
+- **Function Calling**: Declare and use tools/functions
+- **Google Search Retrieval**: Enable dynamic search-backed responses
+- **JSON Schema Responses**: Get structured JSON output
+
+## Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+gemini-rs = { path = "path/to/gemini-rs" }
+tokio = { version = "1", features = ["full"] }
+```
+
+## Quick Start
+
+```rust
+use gemini_rs::prelude::*;
+use gcp_auth::AuthenticationManager;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Authenticate with GCP
+    let provider = AuthenticationManager::new();
+    
+    // Create client
+    let client = GeminiClient::new(
+        provider,
+        "us-central1-aiplatform.googleapis.com".to_string(),
+        "your-project-id".to_string(),
+        "us-central1".to_string(),
+    );
+    
+    // Generate content
+    let request = GenerateContentRequest::builder()
+        .contents(vec![Content {
+            role: Some(Role::User),
+            parts: Some(vec![Part::Text("Hello, Gemini!".to_string())]),
+        }])
+        .build();
+    
+    let response = client.generate_content(&request, "gemini-2.0-flash").await?;
+    
+    for candidate in &response.candidates {
+        if let Some(text) = candidate.get_text() {
+            println!("{}", text);
+        }
+    }
+    
+    Ok(())
+}
+```
+
+## Examples
+
+Run the examples in the `examples/` directory:
+
+```bash
+# Generate text
+cargo run --example text-from-text
+
+# Streaming text generation
+cargo run --example text-from-text-streaming
+
+# Multi-turn conversation
+cargo run --example conversation
+
+# Count tokens
+cargo run --example count-tokens
+
+# Generate images
+cargo run --example generate_image
+
+# Text embeddings
+cargo run --example text-embedding
+
+# JSON schema responses
+cargo run --example json-schema
+
+# Safety settings
+cargo run --example safety-setting
+
+# System instructions
+cargo run --example system_instruction
+
+# Google Search Retrieval
+cargo run --example google-search-retrieval
+
+# Google Search tool
+cargo run --example google-search
+```
+
+## API Reference
+
+### Client Methods
+
+| Method | Description |
+|--------|-------------|
+| `generate_content()` | Generate content from a model |
+| `generate_content_stream()` | Stream content generation responses |
+| `stream_generate_content()` | Stream content using a queue-based approach |
+| `prompt_conversation()` | Send a conversation prompt and get response |
+| `text_embeddings()` | Generate text embeddings |
+| `count_tokens()` | Count tokens in a request |
+| `predict_image()` | Generate/predict images |
+
+### Supported Models
+
+The library works with all Vertex AI Gemini models, including:
+- `gemini-2.0-flash`
+- `gemini-2.0-flash-lite`
+- `gemini-1.5-pro`
+- `gemini-1.5-flash`
+- `text-embedding-004`
+- `imagen-3.0-generate-002`
+
+## License
+
+See [LICENSE](LICENSE) for details.