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/multimodal.rs (line 10)

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

    session.ask(vec!["Where is there in this pdf".into(), InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap().into()]);

    let response = ai.ask(&mut session).await.unwrap();
    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
}
#[tokio::main]
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);

    println!("--- Multimodal (Images/Files) Example ---");

    // Use MarkdownToParts to easily parse a string with image/file markers
    // It supports both URLs and local file paths!
    let content = "Describe this image: ![image](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)";
    println!("Processing: {}", content);

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

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

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

examples/structured_output.rs (line 26)

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");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Structured Output (JSON Mode) Example ---");

    // Enable JSON mode by passing the generated schema
    let ai = ai.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_string(prompt)).await.unwrap();

    // Extract and deserialize the JSON response
    if let Ok(review) = response.get_json::<MovieReview>() {
        println!("\nGemini (Structured):");
        println!("{:#?}", review);
    } else {
        println!("\nFailed to parse JSON response: {}", 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.0-flash-thinking-exp
    let ai = Gemini::new(api_key, "gemini-2.0-flash-thinking-exp", None)
        .set_thinking_config(ThinkingConfig::new(true, 1024));

    println!("--- Thinking Mode Example ---");
    let prompt = "How many 'r's are in the word strawberry? Think step by step.";
    println!("User: {}\n", prompt);

    let response = ai.ask(session.ask_string(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 13)

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", None);

    println!("--- Basic Chat Example ---");

    // 3. Ask a question
    let prompt = "What are the benefits of using Rust for systems programming?";
    println!("User: {}", prompt);

    let response = ai.ask(session.ask_string(prompt)).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);

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

    // Start a streaming request
    let mut response_stream = ai.ask_as_stream(session.ask_string(prompt).clone()).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.
}

examples/function_calling.rs (line 35)

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(),
        ])]);

    println!("--- Function Calling Example ---");
    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_string(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 new_with_timeout( api_key: impl Into<String>, model: impl Into<String>, sys_prompt: Option<SystemInstruction>, api_timeout: Duration, ) -> Self

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 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.0-flash-thinking-exp
    let ai = Gemini::new(api_key, "gemini-2.0-flash-thinking-exp", None)
        .set_thinking_config(ThinkingConfig::new(true, 1024));

    println!("--- Thinking Mode Example ---");
    let prompt = "How many 'r's are in the word strawberry? Think step by step.";
    println!("User: {}\n", prompt);

    let response = ai.ask(session.ask_string(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

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 31)

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");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Structured Output (JSON Mode) Example ---");

    // Enable JSON mode by passing the generated schema
    let ai = ai.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_string(prompt)).await.unwrap();

    // Extract and deserialize the JSON response
    if let Ok(review) = response.get_json::<MovieReview>() {
        println!("\nGemini (Structured):");
        println!("{:#?}", review);
    } else {
        println!("\nFailed to parse JSON response: {}", response.get_chat().get_text_no_think(""));
    }
}

pub fn unset_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-39)

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(),
        ])]);

    println!("--- Function Calling Example ---");
    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_string(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 unset_tools(self) -> Self

Removes all tools.

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/multimodal.rs (line 14)

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

    session.ask(vec!["Where is there in this pdf".into(), InlineData::from_url("https://bitmesra.ac.in/UploadedDocuments/admingo/files/221225_List%20of%20Holiday_2026_26.pdf").await.unwrap().into()]);

    let response = ai.ask(&mut session).await.unwrap();
    println!("\nGemini: {}", response.get_chat().get_text_no_think(""));
}
#[tokio::main]
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);

    println!("--- Multimodal (Images/Files) Example ---");

    // Use MarkdownToParts to easily parse a string with image/file markers
    // It supports both URLs and local file paths!
    let content = "Describe this image: ![image](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)";
    println!("Processing: {}", content);

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

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

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

examples/structured_output.rs (line 36)

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");
    let ai = Gemini::new(api_key, "gemini-2.5-flash", None);

    println!("--- Structured Output (JSON Mode) Example ---");

    // Enable JSON mode by passing the generated schema
    let ai = ai.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_string(prompt)).await.unwrap();

    // Extract and deserialize the JSON response
    if let Ok(review) = response.get_json::<MovieReview>() {
        println!("\nGemini (Structured):");
        println!("{:#?}", review);
    } else {
        println!("\nFailed to parse JSON response: {}", 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.0-flash-thinking-exp
    let ai = Gemini::new(api_key, "gemini-2.0-flash-thinking-exp", None)
        .set_thinking_config(ThinkingConfig::new(true, 1024));

    println!("--- Thinking Mode Example ---");
    let prompt = "How many 'r's are in the word strawberry? Think step by step.";
    println!("User: {}\n", prompt);

    let response = ai.ask(session.ask_string(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 21)

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", None);

    println!("--- Basic Chat Example ---");

    // 3. Ask a question
    let prompt = "What are the benefits of using Rust for systems programming?";
    println!("User: {}", prompt);

    let response = ai.ask(session.ask_string(prompt)).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 46)

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(),
        ])]);

    println!("--- Function Calling Example ---");
    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_string(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 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_message_text("").unwrap())
.await.unwrap(); // Use _gemini_response.get_text("") to just get the text received in every chunk

while let Some(response) = response_stream.next().await {
    if let Ok(response) = response {
        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_text(""));
    }
}

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);

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

    // Start a streaming request
    let mut response_stream = ai.ask_as_stream(session.ask_string(prompt).clone()).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.
}

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.