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
| Feature | Default | Enables |
|---|---|---|
rustls-tls | yes | TLS via rustls + webpki-roots (no system OpenSSL) |
native-tls | no | TLS via the platform’s native stack instead |
live | yes | live: the bidirectional realtime (WebSocket) API |
blocking | no | gemini_genai::blocking: a synchronous mirror of this API |
mcp | no | gemini_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’sagents.py, a re-export layer over the generated_gaossub-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’sbatches.py.- blocking
- The synchronous (
fn, notasync 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’scaches.pyCaches.- chats
client.chats(): multi-turn chat sessions. Mirrors Python’schats.py.- converters
- Helpers used by the generated
mldevrequest/response converters (generated/): the converter dispatcher and the crate-internal error and object-shape helpers. Thegetv/setvpath accessors live incrate::common(mirroring Python’s_common.py). - credentials
- Credential resources (
client.credentials(), experimental upstream): create, get, list, update and delete credentials. Mirrors Python’scredentials.py. - documents
client.file_search_stores().documents(): Document get/list/delete. Mirrors Python’sdocuments.py.- environments
- Environment resources (
client.environments()): create, get, list and delete environments, and list their files. Mirrors Python’senvironments.py. - errors
- Typed errors for
gemini_genai, mirroring the Python SDK’serrors.py. - file_
search_ stores client.file_search_stores(): File Search store create/get/list/delete/import. Mirrors Python’sfile_search_stores.py.- files
client.files(): file upload/get/list/delete/download. Mirrors Python’sfiles.py.- interactions
- Interactions (
client.interactions()): create (optionally streaming), get, cancel and delete interactions. Mirrors Python’sinteractions.py. - live
client.live(): bidirectional realtime (Live API) sessions over WebSocket. Mirrors Python’slive.py.- live_
music client.live().music(): realtime music generation sessions over WebSocket. Mirrors Python’slive_music.py.- mcp_
utils - MCP tool bridging: wraps every tool exposed by an MCP server (reached
through an
rmcpclientPeer) as acrate::automatic_function_calling_util::FunctionTool, so it can be registered withcrate::types::Tool::from_functionand driven by the automatic function calling loop incrate::extra_utils, the same as a plain Rust callable built withfunction_tool. - models
client.models(): text generation, embeddings, token counting, and model listing/management. Mirrors Python’smodels.pyModels.- operations
client.operations(): long-running operation polling. Mirrors Python’soperations.pyOperations.- 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’stokens.py.- triggers
- Trigger resources (
client.triggers()): create, get, list, update, delete and run triggers, and list their executions. Mirrors Python’striggers.py. - tunings
client.tunings(): fine-tuning job create/get/list/cancel. Mirrors Python’stunings.pyTunings.- types
- Request/response types for the Gemini Developer API.
- voices
- Voice resources (
client.voices()): create, get, list and delete custom voices. Mirrors Python’svoices.py. - webhooks
- Webhook resources (
client.webhooks()): create, get, list, update, delete, ping webhooks and rotate their signing secret. Mirrors Python’swebhooks.py.
Structs§
- Client
- The entry point for all Gemini API calls:
Client::new()orClient::builder(), thenclient.models(),client.chats(), etc. - Client
Builder - Builder for
Client. SeeClient::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.