Crate api_gemini 

Gemini API Client for Rust

A Rust client library for Google’s Gemini API.

Governing Principle : “Thin Client, Rich API”

This client exposes all server-side functionality transparently while maintaining zero client-side intelligence or automatic behaviors. The client is a transparent window to the Gemini API, not a smart assistant that makes decisions for developers.

Key principles:

• API Transparency: One-to-one mapping with Gemini API endpoints
• Zero Client Intelligence: No automatic behaviors or magic thresholds
• Explicit Control: Developer decides when, how, and why operations occur
• Information vs Action: Clear separation between data retrieval and state changes

Enterprise Reliability Features

The following enterprise reliability features are explicitly allowed when implemented with explicit configuration and transparent operation:

• Configurable Retry Logic: Exponential backoff with explicit configuration
• Circuit Breaker Pattern: Failure threshold management with transparent state
• Rate Limiting: Request throttling with explicit rate configuration
• Failover Support: Multi-endpoint configuration and automatic switching
• Health Checks: Periodic endpoint health verification and monitoring

State Management Policy

✅ ALLOWED: Runtime-Stateful, Process-Stateless

• Connection pools, circuit breaker state, rate limiting buckets
• Retry logic state, failover state, health check state
• Runtime state that dies with the process
• No persistent storage or cross-process state

❌ PROHIBITED: Process-Persistent State

• File storage, databases, configuration accumulation
• State that survives process restarts

Implementation Requirements:

• Feature gating behind cargo features (retry, circuit_breaker, rate_limiting, failover, health_checks)
• Explicit configuration required (no automatic enabling)
• Transparent method naming (e.g., execute_with_retries(), execute_with_circuit_breaker())
• Zero overhead when features disabled

api_gemini

Comprehensive Rust client for the Google Gemini API with complete type-safe access to all endpoints.

🎯 Architecture: Stateless HTTP Client

This API crate is designed as a stateless HTTP client with zero persistence requirements. It provides:

• Direct HTTP calls to the Google Gemini API
• In-memory operation state only (resets on restart)
• No external storage dependencies (databases, files, caches)
• No configuration persistence beyond environment variables

This ensures lightweight, containerized deployments and eliminates operational complexity.

🏛️ Governing Principle: “Thin Client, Rich API”

Expose all server-side functionality transparently while maintaining zero client-side intelligence or automatic behaviors.

Key principles:

• API Transparency: One-to-one mapping with Gemini API endpoints
• Zero Client Intelligence: No automatic behaviors or magic thresholds
• Explicit Control: Developer decides when, how, and why operations occur
• Information vs Action: Clear separation between data retrieval and state changes

Scope

In Scope

• Text generation (single and multi-turn conversations)
• Streaming responses with pause/resume/cancel
• Vision and multimodal content processing
• Function calling with AUTO/ANY/NONE modes
• Google Search grounding with citations
• System instructions for behavior control
• Code execution (Python)
• Model tuning and fine-tuning
• Embeddings generation
• Token counting
• Server-side content caching
• Safety settings and content filtering
• Enterprise reliability (retry, circuit breaker, rate limiting)
• Synchronous API wrapper

Out of Scope

• Model hosting or training infrastructure
• Persistent state management
• Business logic or application features
• Mock servers or test stubs

Features

Core Capabilities:

• Type-safe request/response models with compile-time guarantees
• Async/await built on Tokio for high-performance operations
• Complete synchronous wrapper for blocking operations
• Builder pattern with method chaining

Advanced Features:

• Google Search grounding with real-time web search
• Enhanced function calling with precise mode control
• System instructions for model behavior
• Code execution with configurable environments
• Model tuning with hyperparameter optimization
• Server-side caching for context management

Enterprise Reliability:

• Automatic retries with exponential backoff
• Circuit breaker for fault tolerance
• Rate limiting and quota management
• Request caching for performance
• Streaming control (pause, resume, cancel)
• Dynamic configuration with hot-reload

Installation

Add to your Cargo.toml:

[dependencies]
api_gemini = "0.2.0"
tokio = { version = "1.0", features = ["macros", "rt-multi-thread"] }

Feature Flags

# Default features
api_gemini = "0.2.0"

# With batch operations (infrastructure ready)
api_gemini = { version = "0.2.0", features = ["batch_operations"] }

# With compression support
api_gemini = { version = "0.2.0", features = ["compression"] }

# All features
api_gemini = { version = "0.2.0", features = ["full"] }

Quick Start

use api_gemini::{ client::Client, models::*, error::Error };

#[tokio::main]
async fn main() -> Result< (), Error >
{
  // Create client from GEMINI_API_KEY environment variable
  let client = Client::new().map_err( |_| Error::ConfigurationError( "Failed to create client".to_string() ) )?;

  // Simple text generation
  let request = GenerateContentRequest
  {
    contents: vec!
    [
      Content
      {
        parts: vec![ Part { text: Some( "Write a haiku about programming".to_string() ), ..Default::default() } ],
        role: "user".to_string(),
      }
    ],
    ..Default::default()
  };

  let response = client.models().by_name( "gemini-1.5-pro-latest" ).generate_content( &request ).await?;

  if let Some( text ) = response.candidates.first()
    .and_then( |c| c.content.parts.first() )
    .and_then( |p| p.text.as_ref() )
  {
    println!( "{}", text );
  }

  Ok( () )
}

Authentication

Option 1: Secret File (Recommended)

Create secret/-secret.sh in your project root:

GEMINI_API_KEY="your-api-key-here"

use api_gemini::client::Client;

fn main() -> Result< (), Box< dyn std::error::Error > >
{
  let client = Client::new()?; // Automatically reads from secret/-secret.sh
  Ok( () )
}

Option 2: Environment Variable

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

Option 3: Direct Configuration

use api_gemini::client::Client;

fn main() -> Result< (), Box< dyn std::error::Error > >
{
  let client = Client::builder()
    .api_key( "your-api-key".to_string() )
    .build()?;
  Ok( () )
}

Get your API key from Google AI Studio.

Error Handling

use api_gemini::{ client::Client, error::Error };

async fn example()
{
  let client = Client::new().unwrap();
  match client.models().list().await
  {
    Ok( models ) => println!( "Found {} models", models.models.len() ),
    Err( Error::AuthenticationError( msg ) ) => eprintln!( "Auth failed: {}", msg ),
    Err( Error::RateLimitError( msg ) ) => eprintln!( "Rate limited: {}", msg ),
    Err( Error::ApiError( msg ) ) => eprintln!( "API error: {}", msg ),
    Err( e ) => eprintln!( "Error: {:?}", e ),
  }
}

Testing

Test Coverage

• 485 tests passing (382 nextest + 103 doctests)
• Zero compilation warnings
• Perfect clippy compliance
• 100% documentation coverage for public APIs
• No-mockup policy: all tests use real API integration

Supported Models

Model	Context Window	Vision	Capabilities
gemini-2.5-flash	1M tokens	Yes	Latest stable
gemini-1.5-pro	1M tokens	Yes	Full capabilities
gemini-1.5-flash	1M tokens	Yes	Fast, cost-effective
text-embedding-004	-	No	Embeddings only

Documentation

• Usage Examples - Comprehensive code examples for all features
• API Coverage - Complete endpoint documentation with test counts
• Cookbook - Recipe patterns for common use cases
• Testing Guide - Test organization and coverage details
• Specification - Complete technical specification
• Examples - Runnable example programs

Dependencies

• reqwest: HTTP client with async support
• tokio: Async runtime
• serde: Serialization/deserialization
• workspace_tools: Secret management
• error_tools: Unified error handling

All dependencies workspace-managed for consistency.

Contributing

1. Follow established patterns in existing code
2. Use 2-space indentation consistently
3. Add tests for new functionality
4. Update documentation for public APIs
5. Ensure zero clippy warnings: cargo clippy -- -D warnings
6. Follow zero-tolerance mock policy (real API integration only)

License

MIT

Links

• Google AI Studio - Get your API key
• Gemini API Documentation - Official API docs
• Examples - Comprehensive usage examples
• Specification - Technical specification

Re-exports

pub use internal::http::compression::CompressionConfig;

pub use internal::http::compression::CompressionAlgorithm;

pub use enterprise::CostQuotaManager;

pub use enterprise::CostQuotaConfig;

pub use enterprise::CostQuotaExceededError;

pub use enterprise::ModelPricing;

pub use enterprise::CostUsageMetrics;

pub use diagnostics::InlineData;

pub use diagnostics::CurlOptions;

pub use models::streaming_control::StreamState;

pub use models::streaming_control::StreamControlConfig;

pub use models::streaming_control::StreamControlConfigBuilder;

pub use models::streaming_control::StreamMetrics;

pub use models::streaming_control::StreamMetricsSnapshot;

pub use models::streaming_control::BufferStrategy;

pub use models::streaming_control::MetricsLevel;

pub use models::streaming_control::ControllableStream;

pub use models::streaming_control::ControllableStreamBuilder;

pub use models::*;

Modules

batch_api

Batch Mode API for async job-based processing with 50% cost discount Batch Mode API for async job-based processing with 50% cost discount.

buffered_streaming

Buffered streaming for smoother UX Buffered streaming for smoother UX.

client

Client module containing the main Client struct and builder pattern Client module for interacting with the Gemini API.

comparison

Model comparison and A/B testing functionality Model comparison functionality for A/B testing and model selection.

diagnostics

Diagnostics module for debugging and development tools Diagnostics module for debugging and development tools

enterprise

Enterprise features for production deployments Enterprise features for production deployments.

error

Cached content API implementation Error handling types and utilities

internal

Internal implementation details (exposed for testing)

models

Models module containing all API request and response data structures Type definitions and API operations for the Gemini API.

templates

Request templates for common use cases Request templates for common use cases.

validation

Input validation utilities for API requests Input validation utilities for API requests

websocket

WebSocket streaming integration for real-time bidirectional communication WebSocket streaming implementation for Gemini API integration.