Struct Gemini 

pub struct Gemini { /* private fields */ }

The main client for interacting with the Gemini API.

Use Gemini::new or Gemini::new_with_timeout to create an instance. You can configure various aspects of the request like model, system instructions, generation config, safety settings, and tools using the provided builder-like methods.

Implementations

impl Gemini

pub fn new( api_key: impl Into<String>, model: impl Into<String>, sys_prompt: Option<SystemInstruction>, ) -> Self

Creates a new Gemini client.

Arguments

• api_key - Your Gemini API key. Get one from Google AI studio.
• model - The model variation to use (e.g., “gemini-2.5-flash”). See model variations.
• sys_prompt - Optional system instructions. See system instructions.

Examples found in repository

examples/structured_output.rs (line 30)

async fn main() {
    let mut session = Session::new(2).set_remember_reply(false);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");

    // Enable JSON mode by passing the generated schema
    let ai =
        Gemini::new(api_key, "gemini-2.5-flash", None).set_json_mode(MovieReview::gemini_schema());

    let prompt = "Give me a review for the movie Interstellar.";
    println!("User: {}", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();
    let review: MovieReview = response
        .get_json()
        .expect("Gemini responded with wrong structure");

    println!("Gemini structured output:\n{review:#?}");
}

examples/multimodal.rs (line 25)

async fn main() {
    let mut session = Session::new(6);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    // Use MarkdownToParts to easily parse a string with image/file markers
    // It supports both URLs and local file paths!
    let content = "Describe this image: ![](https://avatars.githubusercontent.com/u/140788315?v=4)";
    println!("Processing: {}", content);

    let parts = MarkdownToParts::new(content, |_| mime::IMAGE_PNG)
        .await
        .process();

    let response = ai.ask(session.ask_parts(parts)).await.unwrap();

    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
}

examples/thinking.rs (line 12)

async fn main() {
    let mut session = Session::new(4);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");

    // Note: Thinking mode requires a supported model like gemini-2.5+
    let ai = Gemini::new(api_key, "gemini-3-flash-preview", None)
        .set_thinking_config(ThinkingConfig::new(true, ThinkingLevel::Low)); //For gemini-2.5 only
    //budget is allowed. Eg. `.set_thinking_config(ThinkingConfig::new(true, 1024))`

    let prompt = "How many 'r's are in the word strawberry?";
    println!("User: {}\n", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();

    // Show the "thoughts" part separately
    let thoughts = response.get_chat().get_thoughts("\n");
    if !thoughts.is_empty() {
        println!("--- Gemini's Thoughts ---\n{}\n", thoughts);
    }

    // Show the final answer
    let answer = response.get_chat().get_text_no_think("");
    println!("--- Gemini's Answer ---\n{}", answer);
}

examples/basic_chat.rs (lines 13-17)

async fn main() {
    // 1. Initialize the session with a history limit (e.g., 6 messages)
    let mut session = Session::new(6);

    // 2. Create the Gemini client
    // Get your API key from https://aistudio.google.com/app/apikey
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(
        api_key,
        "gemini-2.5-flash",
        Some("You are a senior engineer at google".into()),
    );

    // 3. Ask a question
    let prompt = "What are the benefits of using Rust for systems programming?";
    session.ask(prompt).ask("\nKeep you answer short"); // consecutive asks gets concatenated

    println!("User: {:?}", session.get_last_chat().unwrap().parts());
    let response = ai.ask(&mut session).await.unwrap();

    // 4. Print the reply
    // get_text_no_think("") extracts text and ignores "thought" parts (if any)
    let reply = response.get_chat().get_text_no_think("");
    println!("\nGemini: {}", reply);

    // 5. The session now contains the interaction
    println!("\nMessages in history: {}", session.get_history_length());
}

examples/streaming.rs (line 11)

async fn main() {
    let mut session = Session::new(10);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    let prompt = "Write a poem about crab-like robots on Mars.";
    println!("User: {}\n", prompt);
    print!("Gemini: ");
    stdout().flush().unwrap();
    session.ask(prompt);

    // Start a streaming request
    let mut response_stream = ai.ask_as_stream(session).await.unwrap();

    while let Some(chunk_result) = response_stream.next().await {
        match chunk_result {
            Ok(response) => {
                // Get the text from the current chunk
                let text = response.get_chat().get_text_no_think("");
                print!("{text}");
                stdout().flush().unwrap();
            }
            Err(e) => {
                eprintln!("\nError receiving chunk: {e}",);
                break;
            }
        }
    }

    println!("\n\n--- Stream Complete ---");
    // Note: The session passed to ask_as_stream is updated as you exhaust the stream.
    session = response_stream.get_session_owned();
    println!("Updated session: {session:?}")
}

examples/function_calling.rs (line 36)

async fn main() -> Result<(), Box<dyn Error>> {
    let mut session = Session::new(10);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");

    // 1. Initialize Gemini and register tools
    let ai =
        Gemini::new(api_key, "gemini-2.5-flash", None).set_tools(vec![Tool::FunctionDeclarations(
            vec![
                add_numbers::gemini_schema(),
                get_temperature::gemini_schema(),
            ],
        )]);

    let prompt = "What is 123.45 plus 678.9, and what's the weather like in London?";
    println!("User: {}\n", prompt);

    // 2. Ask Gemini. It might reply with one or more function calls.
    let mut response = ai.ask(session.ask(prompt)).await?;

    // 3. Loop to handle potential multiple rounds of function calls
    loop {
        if response.get_chat().has_function_call() {
            println!("Gemini requested function calls...");

            // 4. Use the macro to execute all requested calls and update the session
            let results = execute_function_calls!(session, add_numbers, get_temperature);

            for (idx, res) in results.iter().enumerate() {
                if let Some(r) = res {
                    println!("  Call #{} result: {:?}", idx, r);
                }
            }

            // 5. Send the results back to Gemini to get the final natural language response
            response = ai.ask(&mut session).await?;
        } else {
            // No more function calls, show the final response
            println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
            break;
        }
    }

    Ok(())
}

Additional examples can be found in:

• examples/context_caching.rs

pub fn new_with_timeout( api_key: impl Into<String>, model: impl Into<String>, sys_prompt: Option<SystemInstruction>, api_timeout: Duration, ) -> Self

👎Deprecated

Creates a new Gemini client with a custom API timeout.

Arguments

• api_key - Your Gemini API key.
• model - The model variation to use.
• sys_prompt - Optional system instructions.
• api_timeout - Custom duration for request timeouts.

pub fn new_with_client( api_key: impl Into<String>, model: impl Into<String>, sys_prompt: Option<SystemInstruction>, client: Client, ) -> Self

Creates a new Gemini client with a custom API reqwest::Client.

Arguments

• api_key - Your Gemini API key.
• model - The model variation to use.
• sys_prompt - Optional system instructions.
• client - reqwest::Client to request gemini API.

pub fn set_generation_config(&mut self) -> &mut Value

Returns a mutable reference to the generation configuration. If not already set, initializes it to an empty object.

See Gemini docs for schema details.

pub fn set_tool_config(self, config: ToolConfig) -> Self

pub fn set_thinking_config(self, config: ThinkingConfig) -> Self

Examples found in repository

examples/thinking.rs (line 13)

async fn main() {
    let mut session = Session::new(4);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");

    // Note: Thinking mode requires a supported model like gemini-2.5+
    let ai = Gemini::new(api_key, "gemini-3-flash-preview", None)
        .set_thinking_config(ThinkingConfig::new(true, ThinkingLevel::Low)); //For gemini-2.5 only
    //budget is allowed. Eg. `.set_thinking_config(ThinkingConfig::new(true, 1024))`

    let prompt = "How many 'r's are in the word strawberry?";
    println!("User: {}\n", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();

    // Show the "thoughts" part separately
    let thoughts = response.get_chat().get_thoughts("\n");
    if !thoughts.is_empty() {
        println!("--- Gemini's Thoughts ---\n{}\n", thoughts);
    }

    // Show the final answer
    let answer = response.get_chat().get_text_no_think("");
    println!("--- Gemini's Answer ---\n{}", answer);
}

pub fn set_model(self, model: impl Into<String>) -> Self

pub fn set_sys_prompt(self, sys_prompt: Option<SystemInstruction>) -> Self

Warning

Changing sys_prompt in middle of a conversation can confuse the model.

pub fn set_safety_settings(self, settings: Option<Vec<SafetySetting>>) -> Self

pub fn set_api_key(self, api_key: impl Into<String>) -> Self

pub fn set_json_mode(self, schema: Value) -> Self

Sets the response format to JSON mode with a specific schema.

To use a Rust struct as a schema, decorate it with #[gemini_schema] and pass StructName::gemini_schema().

Arguments

• schema - The JSON schema for the response. See Gemini Schema docs.

Examples found in repository

examples/structured_output.rs (line 30)

async fn main() {
    let mut session = Session::new(2).set_remember_reply(false);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");

    // Enable JSON mode by passing the generated schema
    let ai =
        Gemini::new(api_key, "gemini-2.5-flash", None).set_json_mode(MovieReview::gemini_schema());

    let prompt = "Give me a review for the movie Interstellar.";
    println!("User: {}", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();
    let review: MovieReview = response
        .get_json()
        .expect("Gemini responded with wrong structure");

    println!("Gemini structured output:\n{review:#?}");
}

pub fn remove_json_mode(self) -> Self

pub fn set_tools(self, tools: Vec<Tool>) -> Self

Sets the tools (functions) available to the model.

Examples found in repository

examples/function_calling.rs (lines 36-41)

async fn main() -> Result<(), Box<dyn Error>> {
    let mut session = Session::new(10);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");

    // 1. Initialize Gemini and register tools
    let ai =
        Gemini::new(api_key, "gemini-2.5-flash", None).set_tools(vec![Tool::FunctionDeclarations(
            vec![
                add_numbers::gemini_schema(),
                get_temperature::gemini_schema(),
            ],
        )]);

    let prompt = "What is 123.45 plus 678.9, and what's the weather like in London?";
    println!("User: {}\n", prompt);

    // 2. Ask Gemini. It might reply with one or more function calls.
    let mut response = ai.ask(session.ask(prompt)).await?;

    // 3. Loop to handle potential multiple rounds of function calls
    loop {
        if response.get_chat().has_function_call() {
            println!("Gemini requested function calls...");

            // 4. Use the macro to execute all requested calls and update the session
            let results = execute_function_calls!(session, add_numbers, get_temperature);

            for (idx, res) in results.iter().enumerate() {
                if let Some(r) = res {
                    println!("  Call #{} result: {:?}", idx, r);
                }
            }

            // 5. Send the results back to Gemini to get the final natural language response
            response = ai.ask(&mut session).await?;
        } else {
            // No more function calls, show the final response
            println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
            break;
        }
    }

    Ok(())
}

pub fn remove_tools(self) -> Self

Removes all tools.

pub fn set_cached_content(self, name: impl Into<String>) -> Self

Examples found in repository

examples/context_caching.rs (line 38)

async fn main() {
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);
    let mut session = Session::new(10);

    //Faking big context for example
    session.ask("What is there in this pdf".repeat(200))
        .ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let cached_content_req = CachedContentBuilder::new("gemini-2.5-flash")
        .display_name("Simulated Large Doc")
        .contents(session.get_history_owned().into_iter().collect())
        .ttl(Duration::from_secs(300))
        .build()
        .unwrap();

    println!("Creating cache...");
    match ai.create_cache(&cached_content_req).await {
        Ok(cache) => {
            println!("Cache created: {}", cache.name().as_ref().unwrap());

            // 2. Use the cache in a request
            let mut session = Session::new(10);
            let prompt = "Summarize the cached document.";
            println!("User: {}", prompt);

            // Create a new client instance that uses the cache
            let ai_with_cache = ai
                .clone()
                .set_cached_content(cache.name().as_ref().unwrap());

            match ai_with_cache.ask(session.ask(prompt)).await {
                Ok(response) => {
                    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
                }
                Err(e) => eprintln!("Error asking Gemini: {:?}", e),
            }

            // 3. List caches
            println!("\nListing caches...");
            match ai.list_caches().await {
                Ok(list) => {
                    if let Some(caches) = list.cached_contents() {
                        for c in caches {
                            println!("- {}", c.name().as_ref().unwrap_or(&"Unknown".to_string()));
                        }
                    } else {
                        println!("No caches found.");
                    }
                }
                Err(e) => eprintln!("Error listing caches: {:?}", e),
            }

            // 4. Delete the cache
            println!("\nDeleting cache...");
            match ai.delete_cache(cache.name().as_ref().unwrap()).await {
                Ok(_) => println!("Cache deleted."),
                Err(e) => eprintln!("Error deleting cache: {:?}", e),
            }
        }
        Err(e) => {
            eprintln!("Failed to create cache: {:?}", e);
        }
    }
}

pub fn remove_cached_content(self) -> Self

pub async fn create_cache( &self, cached_content: &CachedContent, ) -> Result<CachedContent, GeminiResponseError>

Examples found in repository

examples/context_caching.rs (line 26)

async fn main() {
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);
    let mut session = Session::new(10);

    //Faking big context for example
    session.ask("What is there in this pdf".repeat(200))
        .ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let cached_content_req = CachedContentBuilder::new("gemini-2.5-flash")
        .display_name("Simulated Large Doc")
        .contents(session.get_history_owned().into_iter().collect())
        .ttl(Duration::from_secs(300))
        .build()
        .unwrap();

    println!("Creating cache...");
    match ai.create_cache(&cached_content_req).await {
        Ok(cache) => {
            println!("Cache created: {}", cache.name().as_ref().unwrap());

            // 2. Use the cache in a request
            let mut session = Session::new(10);
            let prompt = "Summarize the cached document.";
            println!("User: {}", prompt);

            // Create a new client instance that uses the cache
            let ai_with_cache = ai
                .clone()
                .set_cached_content(cache.name().as_ref().unwrap());

            match ai_with_cache.ask(session.ask(prompt)).await {
                Ok(response) => {
                    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
                }
                Err(e) => eprintln!("Error asking Gemini: {:?}", e),
            }

            // 3. List caches
            println!("\nListing caches...");
            match ai.list_caches().await {
                Ok(list) => {
                    if let Some(caches) = list.cached_contents() {
                        for c in caches {
                            println!("- {}", c.name().as_ref().unwrap_or(&"Unknown".to_string()));
                        }
                    } else {
                        println!("No caches found.");
                    }
                }
                Err(e) => eprintln!("Error listing caches: {:?}", e),
            }

            // 4. Delete the cache
            println!("\nDeleting cache...");
            match ai.delete_cache(cache.name().as_ref().unwrap()).await {
                Ok(_) => println!("Cache deleted."),
                Err(e) => eprintln!("Error deleting cache: {:?}", e),
            }
        }
        Err(e) => {
            eprintln!("Failed to create cache: {:?}", e);
        }
    }
}

pub async fn list_caches( &self, ) -> Result<CachedContentList, GeminiResponseError>

Examples found in repository

examples/context_caching.rs (line 49)

async fn main() {
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);
    let mut session = Session::new(10);

    //Faking big context for example
    session.ask("What is there in this pdf".repeat(200))
        .ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let cached_content_req = CachedContentBuilder::new("gemini-2.5-flash")
        .display_name("Simulated Large Doc")
        .contents(session.get_history_owned().into_iter().collect())
        .ttl(Duration::from_secs(300))
        .build()
        .unwrap();

    println!("Creating cache...");
    match ai.create_cache(&cached_content_req).await {
        Ok(cache) => {
            println!("Cache created: {}", cache.name().as_ref().unwrap());

            // 2. Use the cache in a request
            let mut session = Session::new(10);
            let prompt = "Summarize the cached document.";
            println!("User: {}", prompt);

            // Create a new client instance that uses the cache
            let ai_with_cache = ai
                .clone()
                .set_cached_content(cache.name().as_ref().unwrap());

            match ai_with_cache.ask(session.ask(prompt)).await {
                Ok(response) => {
                    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
                }
                Err(e) => eprintln!("Error asking Gemini: {:?}", e),
            }

            // 3. List caches
            println!("\nListing caches...");
            match ai.list_caches().await {
                Ok(list) => {
                    if let Some(caches) = list.cached_contents() {
                        for c in caches {
                            println!("- {}", c.name().as_ref().unwrap_or(&"Unknown".to_string()));
                        }
                    } else {
                        println!("No caches found.");
                    }
                }
                Err(e) => eprintln!("Error listing caches: {:?}", e),
            }

            // 4. Delete the cache
            println!("\nDeleting cache...");
            match ai.delete_cache(cache.name().as_ref().unwrap()).await {
                Ok(_) => println!("Cache deleted."),
                Err(e) => eprintln!("Error deleting cache: {:?}", e),
            }
        }
        Err(e) => {
            eprintln!("Failed to create cache: {:?}", e);
        }
    }
}

pub async fn get_cache( &self, name: &str, ) -> Result<CachedContent, GeminiResponseError>

pub async fn update_cache( &self, name: &str, update: &CachedContentUpdate, ) -> Result<CachedContent, GeminiResponseError>

pub async fn delete_cache(&self, name: &str) -> Result<(), GeminiResponseError>

Examples found in repository

examples/context_caching.rs (line 64)

async fn main() {
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);
    let mut session = Session::new(10);

    //Faking big context for example
    session.ask("What is there in this pdf".repeat(200))
        .ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let cached_content_req = CachedContentBuilder::new("gemini-2.5-flash")
        .display_name("Simulated Large Doc")
        .contents(session.get_history_owned().into_iter().collect())
        .ttl(Duration::from_secs(300))
        .build()
        .unwrap();

    println!("Creating cache...");
    match ai.create_cache(&cached_content_req).await {
        Ok(cache) => {
            println!("Cache created: {}", cache.name().as_ref().unwrap());

            // 2. Use the cache in a request
            let mut session = Session::new(10);
            let prompt = "Summarize the cached document.";
            println!("User: {}", prompt);

            // Create a new client instance that uses the cache
            let ai_with_cache = ai
                .clone()
                .set_cached_content(cache.name().as_ref().unwrap());

            match ai_with_cache.ask(session.ask(prompt)).await {
                Ok(response) => {
                    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
                }
                Err(e) => eprintln!("Error asking Gemini: {:?}", e),
            }

            // 3. List caches
            println!("\nListing caches...");
            match ai.list_caches().await {
                Ok(list) => {
                    if let Some(caches) = list.cached_contents() {
                        for c in caches {
                            println!("- {}", c.name().as_ref().unwrap_or(&"Unknown".to_string()));
                        }
                    } else {
                        println!("No caches found.");
                    }
                }
                Err(e) => eprintln!("Error listing caches: {:?}", e),
            }

            // 4. Delete the cache
            println!("\nDeleting cache...");
            match ai.delete_cache(cache.name().as_ref().unwrap()).await {
                Ok(_) => println!("Cache deleted."),
                Err(e) => eprintln!("Error deleting cache: {:?}", e),
            }
        }
        Err(e) => {
            eprintln!("Failed to create cache: {:?}", e);
        }
    }
}

pub async fn ask( &self, session: &mut Session, ) -> Result<GeminiResponse, GeminiResponseError>

Sends a prompt to the model and waits for the full response.

Updates the session history with the model’s reply.

Errors

Returns GeminiResponseError::NothingToRespond if the last message in history is from the model.

Examples found in repository

examples/structured_output.rs (line 35)

async fn main() {
    let mut session = Session::new(2).set_remember_reply(false);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");

    // Enable JSON mode by passing the generated schema
    let ai =
        Gemini::new(api_key, "gemini-2.5-flash", None).set_json_mode(MovieReview::gemini_schema());

    let prompt = "Give me a review for the movie Interstellar.";
    println!("User: {}", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();
    let review: MovieReview = response
        .get_json()
        .expect("Gemini responded with wrong structure");

    println!("Gemini structured output:\n{review:#?}");
}

examples/multimodal.rs (line 36)

async fn main() {
    let mut session = Session::new(6);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    // Use MarkdownToParts to easily parse a string with image/file markers
    // It supports both URLs and local file paths!
    let content = "Describe this image: ![](https://avatars.githubusercontent.com/u/140788315?v=4)";
    println!("Processing: {}", content);

    let parts = MarkdownToParts::new(content, |_| mime::IMAGE_PNG)
        .await
        .process();

    let response = ai.ask(session.ask_parts(parts)).await.unwrap();

    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
}

examples/thinking.rs (line 19)

async fn main() {
    let mut session = Session::new(4);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");

    // Note: Thinking mode requires a supported model like gemini-2.5+
    let ai = Gemini::new(api_key, "gemini-3-flash-preview", None)
        .set_thinking_config(ThinkingConfig::new(true, ThinkingLevel::Low)); //For gemini-2.5 only
    //budget is allowed. Eg. `.set_thinking_config(ThinkingConfig::new(true, 1024))`

    let prompt = "How many 'r's are in the word strawberry?";
    println!("User: {}\n", prompt);

    let response = ai.ask(session.ask(prompt)).await.unwrap();

    // Show the "thoughts" part separately
    let thoughts = response.get_chat().get_thoughts("\n");
    if !thoughts.is_empty() {
        println!("--- Gemini's Thoughts ---\n{}\n", thoughts);
    }

    // Show the final answer
    let answer = response.get_chat().get_text_no_think("");
    println!("--- Gemini's Answer ---\n{}", answer);
}

examples/basic_chat.rs (line 24)

async fn main() {
    // 1. Initialize the session with a history limit (e.g., 6 messages)
    let mut session = Session::new(6);

    // 2. Create the Gemini client
    // Get your API key from https://aistudio.google.com/app/apikey
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(
        api_key,
        "gemini-2.5-flash",
        Some("You are a senior engineer at google".into()),
    );

    // 3. Ask a question
    let prompt = "What are the benefits of using Rust for systems programming?";
    session.ask(prompt).ask("\nKeep you answer short"); // consecutive asks gets concatenated

    println!("User: {:?}", session.get_last_chat().unwrap().parts());
    let response = ai.ask(&mut session).await.unwrap();

    // 4. Print the reply
    // get_text_no_think("") extracts text and ignores "thought" parts (if any)
    let reply = response.get_chat().get_text_no_think("");
    println!("\nGemini: {}", reply);

    // 5. The session now contains the interaction
    println!("\nMessages in history: {}", session.get_history_length());
}

examples/function_calling.rs (line 47)

async fn main() -> Result<(), Box<dyn Error>> {
    let mut session = Session::new(10);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");

    // 1. Initialize Gemini and register tools
    let ai =
        Gemini::new(api_key, "gemini-2.5-flash", None).set_tools(vec![Tool::FunctionDeclarations(
            vec![
                add_numbers::gemini_schema(),
                get_temperature::gemini_schema(),
            ],
        )]);

    let prompt = "What is 123.45 plus 678.9, and what's the weather like in London?";
    println!("User: {}\n", prompt);

    // 2. Ask Gemini. It might reply with one or more function calls.
    let mut response = ai.ask(session.ask(prompt)).await?;

    // 3. Loop to handle potential multiple rounds of function calls
    loop {
        if response.get_chat().has_function_call() {
            println!("Gemini requested function calls...");

            // 4. Use the macro to execute all requested calls and update the session
            let results = execute_function_calls!(session, add_numbers, get_temperature);

            for (idx, res) in results.iter().enumerate() {
                if let Some(r) = res {
                    println!("  Call #{} result: {:?}", idx, r);
                }
            }

            // 5. Send the results back to Gemini to get the final natural language response
            response = ai.ask(&mut session).await?;
        } else {
            // No more function calls, show the final response
            println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
            break;
        }
    }

    Ok(())
}

examples/context_caching.rs (line 40)

async fn main() {
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);
    let mut session = Session::new(10);

    //Faking big context for example
    session.ask("What is there in this pdf".repeat(200))
        .ask(InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap());

    let cached_content_req = CachedContentBuilder::new("gemini-2.5-flash")
        .display_name("Simulated Large Doc")
        .contents(session.get_history_owned().into_iter().collect())
        .ttl(Duration::from_secs(300))
        .build()
        .unwrap();

    println!("Creating cache...");
    match ai.create_cache(&cached_content_req).await {
        Ok(cache) => {
            println!("Cache created: {}", cache.name().as_ref().unwrap());

            // 2. Use the cache in a request
            let mut session = Session::new(10);
            let prompt = "Summarize the cached document.";
            println!("User: {}", prompt);

            // Create a new client instance that uses the cache
            let ai_with_cache = ai
                .clone()
                .set_cached_content(cache.name().as_ref().unwrap());

            match ai_with_cache.ask(session.ask(prompt)).await {
                Ok(response) => {
                    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
                }
                Err(e) => eprintln!("Error asking Gemini: {:?}", e),
            }

            // 3. List caches
            println!("\nListing caches...");
            match ai.list_caches().await {
                Ok(list) => {
                    if let Some(caches) = list.cached_contents() {
                        for c in caches {
                            println!("- {}", c.name().as_ref().unwrap_or(&"Unknown".to_string()));
                        }
                    } else {
                        println!("No caches found.");
                    }
                }
                Err(e) => eprintln!("Error listing caches: {:?}", e),
            }

            // 4. Delete the cache
            println!("\nDeleting cache...");
            match ai.delete_cache(cache.name().as_ref().unwrap()).await {
                Ok(_) => println!("Cache deleted."),
                Err(e) => eprintln!("Error deleting cache: {:?}", e),
            }
        }
        Err(e) => {
            eprintln!("Failed to create cache: {:?}", e);
        }
    }
}

pub async fn ask_as_stream_with_extractor<F, StreamType>( &self, session: Session, data_extractor: F, ) -> Result<ResponseStream<F, StreamType>, (Session, GeminiResponseError)>

where F: FnMut(&Session, GeminiResponse) -> StreamType,

Warning

You must read the response stream to get reply stored context in session. data_extractor is used to extract data that you get as a stream of futures.

Example

use futures::StreamExt
let mut response_stream = gemini.ask_as_stream_with_extractor(session,
     |session, _gemini_response| session.get_last_chat().unwrap().get_text_no_think("\n"))
    .await.unwrap(); // Use _gemini_response.get_text("") to just get the text received in every chunk
while let Some(response) = response_stream.next().await {
    println!("{}", response);
}

pub async fn ask_as_stream( &self, session: Session, ) -> Result<GeminiResponseStream, (Session, GeminiResponseError)>

Sends a prompt to the model and returns a stream of responses.

Warning

You must exhaust the response stream to ensure the session history is correctly updated.

Example

use futures::StreamExt;
let mut response_stream = gemini.ask_as_stream(session).await.unwrap();

while let Some(response) = response_stream.next().await {
    if let Ok(response) = response {
        println!("{}", response.get_chat().get_text_no_think("\n"));
    }
}

Examples found in repository

examples/streaming.rs (line 20)

async fn main() {
    let mut session = Session::new(10);
    let api_key = env::var("GEMINI_API_KEY").expect("GEMINI_API_KEY must be set");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    let prompt = "Write a poem about crab-like robots on Mars.";
    println!("User: {}\n", prompt);
    print!("Gemini: ");
    stdout().flush().unwrap();
    session.ask(prompt);

    // Start a streaming request
    let mut response_stream = ai.ask_as_stream(session).await.unwrap();

    while let Some(chunk_result) = response_stream.next().await {
        match chunk_result {
            Ok(response) => {
                // Get the text from the current chunk
                let text = response.get_chat().get_text_no_think("");
                print!("{text}");
                stdout().flush().unwrap();
            }
            Err(e) => {
                eprintln!("\nError receiving chunk: {e}",);
                break;
            }
        }
    }

    println!("\n\n--- Stream Complete ---");
    // Note: The session passed to ask_as_stream is updated as you exhaust the stream.
    session = response_stream.get_session_owned();
    println!("Updated session: {session:?}")
}

Trait Implementations

impl Clone for Gemini

fn clone(&self) -> Gemini

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Gemini

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Gemini

fn default() -> Gemini

Returns the “default value” for a type.