Skip to main content

Crate gemini_genai

Crate gemini_genai 

Source
Expand description

Unofficial. An independent Rust port of the Google Gen AI Python SDK (google-genai 2.28.0) for the Gemini Developer API. Not affiliated with, endorsed by, or sponsored by Google. Portions of this crate are derived from google-genai, Copyright 2025 Google LLC, licensed under the Apache License, Version 2.0; see the NOTICE file at the repository root for what is derived and what was changed.

The package is named gemini-genai but its library name is gemini_genai: depend on the former (cargo add gemini-genai) and use gemini_genai::....

Vertex AI is out of scope: asking for it (via ClientBuilder::vertexai, project/location, or the GOOGLE_GENAI_USE_VERTEXAI environment variable) fails fast with Error::UnsupportedBackend.

§Quickstart

use gemini_genai::Client;

let client = Client::new()?;
let response = client
    .models()
    .generate_content("gemini-flash-latest", "Why is the sky blue?", None)
    .await?;
println!("{}", response.text().unwrap_or_default());

Client::new reads the API key from GOOGLE_API_KEY, falling back to GEMINI_API_KEY; Client::builder sets it (and HttpOptions) explicitly. GOOGLE_GEMINI_BASE_URL overrides the API base URL when it is not set on the builder.

§Streaming

use futures_util::StreamExt;
use gemini_genai::Client;

let client = Client::new()?;
let stream = client
    .models()
    .generate_content_stream("gemini-flash-latest", "Write a haiku.", None)
    .await?;

let mut stream = Box::pin(stream);
while let Some(chunk) = stream.next().await {
    print!("{}", chunk?.text().unwrap_or_default());
}

§Structured output

GenerateContentConfig::with_json_schema_of derives the response schema from a plain Rust type via schemars, so the reply parses straight back into it.

use gemini_genai::Client;
use gemini_genai::types::GenerateContentConfig;

#[derive(serde::Deserialize, schemars::JsonSchema)]
struct Capital {
    country: String,
    capital: String,
}

let client = Client::new()?;
let config = GenerateContentConfig::default().with_json_schema_of::<Capital>();
let response = client
    .models()
    .generate_content("gemini-flash-latest", "What is the capital of Japan?", Some(config))
    .await?;

let capital: Capital = serde_json::from_str(&response.text().unwrap_or_default())?;
println!("{} -> {}", capital.country, capital.capital);

§Automatic function calling

function_tool wraps an async Rust function as a model-callable tool; Tool::from_function declares it in GenerateContentConfig, and generate_content then drives the call/response loop itself. See automatic_function_calling_util for the loop’s limits and for the process-wide registry caveat (callables are keyed by function name).

use gemini_genai::function_tool;
use gemini_genai::types::{GenerateContentConfig, Tool};
use gemini_genai::Client;

#[derive(serde::Deserialize, schemars::JsonSchema)]
struct WeatherArgs {
    /// The city to look up.
    city: String,
}

let tool = Tool::from_function(function_tool(
    "get_weather",
    "Returns the current weather for a city.",
    |args: WeatherArgs| async move {
        Ok(serde_json::json!({ "city": args.city, "temperature_c": 21 }))
    },
));

let client = Client::new()?;
let response = client
    .models()
    .generate_content(
        "gemini-flash-latest",
        "What is the weather in Kyoto?",
        Some(GenerateContentConfig { tools: Some(vec![tool]), ..Default::default() }),
    )
    .await?;
println!("{}", response.text().unwrap_or_default());

§Modules

Every API surface hangs off Client, one accessor per Python SDK module: models, chats, files, caches, tunings, batches, operations, file_search_stores (plus documents), tokens, and live. Request/response types live in types, errors in errors, and list endpoints return a Pager<T> with page(), next_page().await, and into_stream().

§Cargo features

FeatureDefaultEnables
rustls-tlsyesTLS via rustls + webpki-roots (no system OpenSSL)
native-tlsnoTLS via the platform’s native stack instead
liveyeslive: the bidirectional realtime (WebSocket) API
blockingnogemini_genai::blocking: a synchronous mirror of this API
mcpnogemini_genai::mcp: exposes MCP server tools to the model

§Errors

Every fallible call returns Result<T>, whose error is the Error enum: Error::Api (boxed ApiError with code, status, message), Error::Http, Error::Json, Error::Io, Error::Validation, Error::UnsupportedByBackend, Error::UnsupportedBackend, Error::FunctionCall, Error::WebSocket (with the live feature), Error::Stream, Error::Upload, Error::NoMorePages, and Error::BlockingInsideRuntime.

use gemini_genai::{ApiError, Error};

fn describe(error: &Error) -> String {
    match error {
        Error::Api(api) if api.code == 429 => "rate limited; back off".to_owned(),
        Error::Api(api) => format!("API error {}: {}", api.code, api.message),
        Error::Validation(message) => format!("bad request: {message}"),
        other => other.to_string(),
    }
}

let error = Error::Api(Box::new(ApiError {
    code: 429,
    status: Some("RESOURCE_EXHAUSTED".to_owned()),
    message: "quota exceeded".to_owned(),
    details: Vec::new(),
    response_headers: std::collections::HashMap::new(),
}));
assert_eq!(describe(&error), "rate limited; back off");

§Further reading

  • docs/parity.md (generated): the full Python-to-Rust method and type mapping, including what is deliberately not ported.
  • docs/migrating-from-python.md: a migration guide for people coming from the Python SDK.

Re-exports§

pub use automatic_function_calling_util::FunctionTool;
pub use automatic_function_calling_util::function_tool;
pub use client::Backend;
pub use client::Client;
pub use client::ClientBuilder;
pub use errors::ApiError;
pub use errors::Error;
pub use errors::Result;
pub use pagers::Pager;

Modules§

agents
Agent resources (client.agents()): create, get, list and delete agents. Mirrors Python’s agents.py, a re-export layer over the generated _gaos sub-SDK.
automatic_function_calling_util
Registering Rust callables (and, via crate::mcp_utils, MCP tools) as model-invocable functions for automatic function calling (AFC).
base_url
Default base URL resolution for the Gemini Developer API.
batches
client.batches(): batch job create/get/list/cancel/delete. Mirrors Python’s batches.py.
blocking
The synchronous (fn, not async fn) wrapper around this crate’s async API (feature = "blocking"). Mirrors the Python SDK’s default (synchronous) surface for callers who don’t want to bring their own Tokio runtime.
caches
client.caches(): context cache create/get/list/update/delete. Mirrors Python’s caches.py Caches.
chats
client.chats(): multi-turn chat sessions. Mirrors Python’s chats.py.
converters
Helpers used by the generated mldev request/response converters (generated/): the converter dispatcher and the crate-internal error and object-shape helpers. The getv/setv path accessors live in crate::common (mirroring Python’s _common.py).
credentials
Credential resources (client.credentials(), experimental upstream): create, get, list, update and delete credentials. Mirrors Python’s credentials.py.
documents
client.file_search_stores().documents(): Document get/list/delete. Mirrors Python’s documents.py.
environments
Environment resources (client.environments()): create, get, list and delete environments, and list their files. Mirrors Python’s environments.py.
errors
Typed errors for gemini_genai, mirroring the Python SDK’s errors.py.
file_search_stores
client.file_search_stores(): File Search store create/get/list/delete/import. Mirrors Python’s file_search_stores.py.
files
client.files(): file upload/get/list/delete/download. Mirrors Python’s files.py.
interactions
Interactions (client.interactions()): create (optionally streaming), get, cancel and delete interactions. Mirrors Python’s interactions.py.
live
client.live(): bidirectional realtime (Live API) sessions over WebSocket. Mirrors Python’s live.py.
live_music
client.live().music(): realtime music generation sessions over WebSocket. Mirrors Python’s live_music.py.
mcp_utils
MCP tool bridging: wraps every tool exposed by an MCP server (reached through an rmcp client Peer) as a crate::automatic_function_calling_util::FunctionTool, so it can be registered with crate::types::Tool::from_function and driven by the automatic function calling loop in crate::extra_utils, the same as a plain Rust callable built with function_tool.
models
client.models(): text generation, embeddings, token counting, and model listing/management. Mirrors Python’s models.py Models.
operations
client.operations(): long-running operation polling. Mirrors Python’s operations.py Operations.
pagers
Paginated list results, mirroring Python’s pagers.py (Pager/AsyncPager).
tokens
client.auth_tokens(): ephemeral auth token creation for the Live API. Mirrors Python’s tokens.py.
triggers
Trigger resources (client.triggers()): create, get, list, update, delete and run triggers, and list their executions. Mirrors Python’s triggers.py.
tunings
client.tunings(): fine-tuning job create/get/list/cancel. Mirrors Python’s tunings.py Tunings.
types
Request/response types for the Gemini Developer API.
voices
Voice resources (client.voices()): create, get, list and delete custom voices. Mirrors Python’s voices.py.
webhooks
Webhook resources (client.webhooks()): create, get, list, update, delete, ping webhooks and rotate their signing secret. Mirrors Python’s webhooks.py.

Structs§

Client
The entry point for all Gemini API calls: Client::new() or Client::builder(), then client.models(), client.chats(), etc.
ClientBuilder
Builder for Client. See Client::builder.

Constants§

UPSTREAM_GENAI_VERSION
The google-genai (Python SDK) release this crate’s generated types and wire converters were produced from, and verified against.