gemini-rust

A comprehensive Rust client library for Google's Gemini 2.5 API.

✨ Features

• 🚀 Complete Gemini 2.5 API Implementation - Full support for all Gemini API endpoints
• 🛠️ Function Calling & Tools - Custom functions and Google Search integration
• 📦 Batch Processing - Efficient batch content generation and embedding
• 💾 Content Caching - Cache system instructions and conversation history for cost optimization
• 🔄 Streaming Responses - Real-time streaming of generated content
• 🧠 Thinking Mode - Support for Gemini 2.5 thinking capabilities
• 🎨 Image Generation - Text-to-image generation and image editing capabilities
• 🎤 Speech Generation - Text-to-speech with single and multi-speaker support
• 🖼️ Multimodal Support - Images and binary data processing
• 📊 Text Embeddings - Advanced embedding generation with multiple task types
• ⚙️ Highly Configurable - Custom models, endpoints, and generation parameters
• 🔒 Type Safe - Comprehensive type definitions with full serde support
• ⚡ Async/Await - Built on tokio for high-performance async operations

📦 Installation

Add this to your Cargo.toml:

[dependencies]
gemini-rust = "1.4.0"

🚀 Quick Start

Basic Content Generation

use gemini_rust::Gemini;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GEMINI_API_KEY")?;
    let client = Gemini::new(api_key)?;

    let response = client
        .generate_content()
        .with_system_prompt("You are a helpful assistant.")
        .with_user_message("Hello, how are you?")
        .execute()
        .await?;

    println!("Response: {}", response.text());
    Ok(())
}

Streaming Responses

use gemini_rust::Gemini;
use futures::TryStreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Gemini::new(std::env::var("GEMINI_API_KEY")?)?;

    let mut stream = client
        .generate_content()
        .with_user_message("Tell me a story about programming")
        .execute_stream()
        .await?;

    while let Some(chunk) = stream.try_next().await? {
        print!("{}", chunk.text());
    }
    Ok(())
}

🛠️ Advanced Features

Function Calling

use gemini_rust::{Gemini, FunctionDeclaration, FunctionParameters, PropertyDetails};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Gemini::new(std::env::var("GEMINI_API_KEY")?)?;

    // Define a custom function
    let weather_function = FunctionDeclaration::new(
        "get_weather",
        "Get the current weather for a location",
        FunctionParameters::object()
            .with_property(
                "location",
                PropertyDetails::string("The city and state, e.g., San Francisco, CA"),
                true,
            )
    );

    let response = client
        .generate_content()
        .with_user_message("What's the weather like in Tokyo?")
        .with_function(weather_function)
        .execute()
        .await?;

    // Handle function calls
    if let Some(function_call) = response.function_calls().first() {
        println!("Function: {}", function_call.name);
        println!("Args: {}", function_call.args);
    }
    Ok(())
}

Image Generation

use gemini_rust::Gemini;
use base64::{engine::general_purpose::STANDARD as BASE64, Engine};
use std::fs;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Gemini::with_model(
        std::env::var("GEMINI_API_KEY")?,
        "models/gemini-2.5-flash-image-preview".to_string()
    )?;

    let response = client
        .generate_content()
        .with_user_message(
            "Create a photorealistic image of a cute robot sitting in a garden, \
             surrounded by colorful flowers. The robot should have a friendly \
             expression and be made of polished metal."
        )
        .execute()
        .await?;

    // Save generated images
    for candidate in response.candidates.iter() {
        if let Some(parts) = &candidate.content.parts {
            for part in parts.iter() {
                if let gemini_rust::Part::InlineData { inline_data } = part {
                    let image_bytes = BASE64.decode(&inline_data.data)?;
                    fs::write("generated_image.png", image_bytes)?;
                    println!("Image saved as generated_image.png");
                }
            }
        }
    }
    Ok(())
}

Speech Generation

use gemini_rust::{Gemini, GenerationConfig, SpeechConfig, VoiceConfig, PrebuiltVoiceConfig};
use base64::{Engine as _, engine::general_purpose};
use std::fs::File;
use std::io::Write;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Gemini::with_model(
        std::env::var("GEMINI_API_KEY")?,
        "models/gemini-2.5-flash-preview-tts".to_string()
    )?;

    let generation_config = GenerationConfig {
        response_modalities: Some(vec!["AUDIO".to_string()]),
        speech_config: Some(SpeechConfig {
            voice_config: Some(VoiceConfig {
                prebuilt_voice_config: Some(PrebuiltVoiceConfig {
                    voice_name: "Puck".to_string(),
                }),
            }),
            multi_speaker_voice_config: None,
        }),
        ..Default::default()
    };

    let response = client
        .generate_content()
        .with_user_message("Hello! Welcome to Gemini text-to-speech.")
        .with_generation_config(generation_config)
        .execute()
        .await?;

    // Save generated audio as PCM format
    for candidate in response.candidates.iter() {
        if let Some(parts) = &candidate.content.parts {
            for part in parts.iter() {
                if let gemini_rust::Part::InlineData { inline_data } = part {
                    if inline_data.mime_type.starts_with("audio/") {
                        let audio_bytes = general_purpose::STANDARD.decode(&inline_data.data)?;
                        let mut file = File::create("speech_output.pcm")?;
                        file.write_all(&audio_bytes)?;
                        println!("Audio saved as speech_output.pcm");
                        println!("Convert to WAV using: ffmpeg -f s16le -ar 24000 -ac 1 -i speech_output.pcm speech_output.wav");
                    }
                }
            }
        }
    }
    Ok(())
}

Google Search Tool

use gemini_rust::{Gemini, Tool};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Gemini::new(std::env::var("GEMINI_API_KEY")?)?;

    let response = client
        .generate_content()
        .with_user_message("What's the latest news about Rust programming language?")
        .with_tool(Tool::google_search())
        .execute()
        .await?;

    println!("Response: {}", response.text());
    Ok(())
}

Thinking Mode (Gemini 2.5)

use gemini_rust::Gemini;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Use Gemini 2.5 Pro for advanced thinking capabilities
    let client = Gemini::pro(std::env::var("GEMINI_API_KEY")?)?;

    let response = client
        .generate_content()
        .with_user_message("Explain quantum computing in simple terms")
        .with_dynamic_thinking()  // Let model decide thinking budget
        .with_thoughts_included(true)  // Include thinking process
        .execute()
        .await?;

    // Access thinking summaries
    for thought in response.thoughts() {
        println!("Thought: {}", thought);
    }

    println!("Response: {}", response.text());
    Ok(())
}

Text Embeddings

use gemini_rust::{Gemini, Model, TaskType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Gemini::with_model(
        std::env::var("GEMINI_API_KEY")?,
        Model::TextEmbedding004
    )?;

    let response = client
        .embed_content()
        .with_text("Hello, this is my text to embed")
        .with_task_type(TaskType::RetrievalDocument)
        .execute()
        .await?;

    println!("Embedding dimensions: {}", response.embedding.values.len());
    Ok(())
}

Cached Content

Cache large context (system instructions, conversation history) to reduce costs and improve performance for repeated API calls:

use gemini_rust::Gemini;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Gemini::new(std::env::var("GEMINI_API_KEY")?)?;

    // Create cached content with system instruction and conversation history
    let cache = client
        .create_cache()
        .with_display_name("My Programming Assistant")?
        .with_system_instruction("You are a helpful programming assistant.")
        .with_user_message("Hello! I'm learning Rust.")
        .with_model_message("Great! I'm here to help you learn Rust programming.")
        .with_ttl(Duration::from_secs(3600)) // Cache for 1 hour
        .execute()
        .await?;

    // Use the cached content for subsequent requests
    let response = client
        .generate_content()
        .with_cached_content(&cache)
        .with_user_message("Can you explain ownership?")
        .execute()
        .await?;

    println!("Response: {}", response.text());

    // Clean up when done
    cache.delete().await.map_err(|(_, e)| e)?;
    Ok(())
}

Batch Processing

The library supports batching multiple content generation requests into a single operation. You can execute the batch directly for a small number of requests. For larger jobs, you should use the execute_as_file() method, which serializes the requests to a JSONL file, uploads it, and initiates the batch job.

use gemini_rust::{Gemini, Message};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Gemini::new(std::env::var("GEMINI_API_KEY")?)?;

    // Create multiple requests
    let request1 = client
        .generate_content()
        .with_user_message("What is the meaning of life?")
        .build();

    let request2 = client
        .generate_content()
        .with_user_message("What is the best programming language?")
        .build();

    // For smaller jobs, execute directly:
    let batch = client
        .batch_generate_content()
        .with_request(request1)
        .with_request(request2)
        .execute()
        .await?;

    // For a large number of requests, use execute_as_file():
    // let batch = client
    //     .batch_generate_content()
    //     .with_requests(many_requests)
    //     .execute_as_file()
    //     .await?;

    println!("Batch Name: {}", batch.name());

    // The `execute()` method polls for completion.
    // You can then immediately check the final status.
    match batch.status().await? {
        gemini_rust::BatchStatus::Succeeded { results } => {
            for item in results {
                match item.response {
                    Ok(response) => {
                        println!("Result for key {}: {}", item.meta.key, response.text());
                    }
                    Err(e) => {
                        println!("Error for key {}: {:?}", item.meta.key, e);
                    }
                }
            }
        }
        status => println!("Batch finished with status: {:?}", status),
    }

    Ok(())
}

Image Processing

use gemini_rust::{Gemini, Blob};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Gemini::new(std::env::var("GEMINI_API_KEY")?)?;

    // Load and encode image as base64
    let image_data = std::fs::read("path/to/image.jpg")?;
    let base64_image = base64::encode(&image_data);

    let blob = Blob::new("image/jpeg", base64_image);

    let response = client
        .generate_content()
        .with_user_message("What's in this image?")
        .with_inline_data("image/jpeg", base64_image)
        .execute()
        .await?;

    println!("Response: {}", response.text());
    Ok(())
}

Generation Configuration

use gemini_rust::{Gemini, GenerationConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Gemini::new(std::env::var("GEMINI_API_KEY")?)?;

    let response = client
        .generate_content()
        .with_user_message("Write a creative story")
        .with_generation_config(GenerationConfig {
            temperature: Some(0.9),
            max_output_tokens: Some(1000),
            top_p: Some(0.8),
            top_k: Some(40),
            stop_sequences: Some(vec!["END".to_string()]),
            ..Default::default()
        })
        .execute()
        .await?;

    println!("Response: {}", response.text());
    Ok(())
}

🔧 Configuration

Custom Models

use gemini_rust::Gemini;

// Use Gemini 2.5 Flash (default)
let client = Gemini::new(api_key)?;

// Use Gemini 2.5 Pro for advanced tasks
let client = Gemini::pro(api_key)?;

// Use specific model
let client = Gemini::with_model(api_key, "models/gemini-1.5-pro".to_string())?;

Custom Base URL

use gemini_rust::Gemini;

// Custom endpoint
let client = Gemini::with_base_url(
    api_key,
    "https://custom-api.example.com/v1/".parse()?
)?;

// Custom model and endpoint
let client = Gemini::with_model_and_base_url(
    api_key,
    "models/gemini-pro".to_string(),
    "https://custom-api.example.com/v1/".parse()?
)?;

📚 Examples

The repository includes comprehensive examples:

Run an example:

GEMINI_API_KEY="your-api-key" cargo run --example simple

🔑 API Key Setup

Get your API key from Google AI Studio and set it as an environment variable:

export GEMINI_API_KEY="your-api-key-here"

🚦 Supported Models

• Gemini 2.5 Flash - Fast, efficient model (default) - Model::Gemini25Flash
• Gemini 2.5 Flash Lite - Lightweight model - Model::Gemini25FlashLite
• Gemini 2.5 Pro - Advanced model with thinking capabilities - Model::Gemini25Pro
• Text Embedding 004 - Latest embedding model - Model::TextEmbedding004
• Custom models - Use Model::Custom(String) or string literals for other models

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Google for providing the Gemini API
• The Rust community for excellent async and HTTP libraries
• Special thanks to @npatsakula for major contributions that made this project more complete
• All contributors who have helped improve this library