Gemini API — SDKs and client libraries
Status: DOCUMENTED; Python google-genai 2.24.0 and @google/genai 2.23.0 are installed in this repo (.venv, node_modules); REST and OpenAI-compat paths LIVE_VERIFIED. Twin: generated/fragments/sdks/gemini-sdks.json.
Sources: https://ai.google.dev/gemini-api/docs/libraries · https://ai.google.dev/gemini-api/docs/migrate · https://ai.google.dev/gemini-api/docs/api-versions · https://ai.google.dev/gemini-api/docs/troubleshooting · https://ai.google.dev/gemini-api/docs/openai · https://ai.google.dev/gemini-api/docs/interactions · sources/gemini/openapi/python-genai-readme.md, python-genai-types.py, js-genai-readme.md
Last verified: 2026-09-18.
1. Official Google GenAI SDK (GA since May 2025)
| Language | Package | Install | Client |
|---|---|---|---|
| Python (≥ 3.10) | google-genai 2.24.0 installed |
pip install google-genai ([aiohttp] extra) |
from google import genai; client = genai.Client() |
| JS / TS | @google/genai 2.23.0 installed |
npm install @google/genai |
new GoogleGenAI({ apiKey }) |
| Go | google.golang.org/genai |
go get google.golang.org/genai |
genai.NewClient(ctx, &genai.ClientConfig{APIKey, Backend: genai.BackendGeminiAPI}) |
| Java | com.google.genai:google-genai |
Maven | Client.builder().apiKey(...).build() (Interactions in com.google.genai.gaos.models.interactions) |
| C# / .NET | Google.GenAI |
dotnet add package Google.GenAI |
new Client() |
| REST | curl | — | x-goog-api-key header |
| OpenAI-compat | openai (Python 3.16.2 installed / Node) |
— | OpenAI(api_key=GEMINI_API_KEY, base_url=".../v1beta/openai/") |
One SDK, two backends: genai.Client() → Gemini Developer API; genai.Client(vertexai=True, project=, location=) or env GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_CLOUD_PROJECT/LOCATION → Gemini Enterprise Agent Platform (Vertex AI). Env keys: GEMINI_API_KEY or GOOGLE_API_KEY (GOOGLE_API_KEY wins if both set).
2. Client options (Python types.HttpOptions, JS httpOptions)
| Option | Python | JS | Notes |
|---|---|---|---|
| API version | `api_version='v1' | 'v1beta' | 'v1alpha'` |
| Base URL / proxy | base_url, base_url_resource_scope, client_args={'proxy':…} |
baseUrl |
gateway/proxy support |
| Headers | headers={} |
headers |
e.g. x-goog-user-project |
| Timeout | timeout (ms) → also X-Server-Timeout |
timeout |
per-client or per-request via config.http_options |
| Retries | retry_options=HttpRetryOptions(attempts, initial_delay, max_delay, exp_base, jitter, http_status_codes) |
(built-in) | default: 429/5xx/timeouts, 4 attempts, ~1 s → 60 s |
| Extra body | extra_body |
— | undocumented fields passthrough |
| Custom transport | httpx_client, httpx_async_client, async_client_args |
— | aiohttp for faster async |
3. Surface map (Python names; JS is camelCase)
| Area | Calls |
|---|---|
| Models | client.models.generate_content / generate_content_stream / count_tokens / compute_tokens / embed_content / list / get / generate_videos (Veo LRO) / generate_images (Imagen — retired on Gemini API); client.aio.* async |
| Config | `GenerateContentConfig(system_instruction, max_output_tokens, thinking_config=ThinkingConfig(thinking_level |
| Function calling | automatic Python function calling (pass callables; automatic_function_calling.disable), FunctionCallingConfig(mode='ANY', allowed_function_names), MCP sessions as tools (experimental; JS mcpToTool) |
| Structured output | response_json_schema (JSON Schema, recommended on Gemini 3) or Pydantic response_schema; response.parsed |
| Chats | client.chats.create(model).send_message(_stream) (client-side history) |
| Files | client.files.upload(file=, config=UploadFileConfig(mime_type, display_name)) / get / list / delete / download |
| Caches | client.caches.create(model=, config=CreateCachedContentConfig(contents, system_instruction, ttl)); explicit caching not available through Interactions |
| Interactions | `client.interactions.create(model= |
| Live | async with client.aio.live.connect(model=, config=LiveConnectConfig(...)) as session: send_client_content / send_realtime_input / send_tool_response / receive(); client.auth_tokens.create (ephemeral); client.aio.live.music.connect (Lyria RealTime) |
| Batches | client.batches.create(model=, src=, config=) / get / list / cancel / delete |
| File Search | client.file_search_stores.create / upload_to_file_search_store / import_file / documents.* |
| Tunings | client.tunings.* present for Vertex; no tunable model on the Developer API |
| Errors | google.genai.errors.APIError(code, message, status, details), ClientError, ServerError; JS ApiError { status, message } |
types.Model (SDK) exposes supported_actions (= REST supportedGenerationMethods), input_token_limit, output_token_limit, temperature, max_temperature, top_p, top_k, version, endpoints/labels/tuned_model_info/checkpoints (Vertex-only fields) — the live thinking boolean is not yet a typed field.
4. Legacy libraries (deprecated 2025-11-30, not maintained)
google-generativeai (Python), @google/generative-ai (JS), github.com/google/generative-ai-go, google_generative_ai (Dart), generative-ai-swift, generative-ai-android. Migration: https://ai.google.dev/gemini-api/docs/migrate. Mobile/web clients → Firebase AI Logic or Genkit; no legacy Java SDK ever existed.
5. OpenAI SDK against Gemini
See openai-compatibility. Live 2026-09-19: chat.completions.create(model="gemini-3.5-flash-lite", max_tokens=8) → "OK.", extra_content.google.thought_signature present, usage 5/2/7.
6. Other integrations documented by Google
Vercel AI SDK, LangGraph, CrewAI, LlamaIndex, Temporal examples; Gemini CLI; Antigravity SDK (agent loop + tools, default model gemini-3.8-flash); gemini-api-dev coding-agent skill and Gemini Docs MCP.