# 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'` | `apiVersion` | default **v1beta**; v1 for the stable surface (Interactions GA) |
| 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|thinking_budget, include_thoughts), response_mime_type, response_schema | response_json_schema, tools=[Tool(google_search=, google_maps=, url_context=, code_execution=, file_search=, computer_use=, function_declarations=)], tool_config, cached_content, safety_settings, media_resolution, http_options)` |
| 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= | agent=, input=, previous_interaction_id=, background=, store=, stream=, generation_config=, tools=)`, `.get`, `.cancel` — Python ≥ 1.55.0, JS ≥ 1.33.0 |
| 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](openai-compatibility.md). 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.