Gemini API — authentication, headers, API versions, regions and terms
Status: DOCUMENTED + LIVE_VERIFIED (header behaviour probed 2026-09-19). Twins: generated/fragments/headers/gemini-headers.json, generated/fragments/endpoints/gemini-models-misc.json.
Sources: https://ai.google.dev/gemini-api/docs/api-key · https://ai.google.dev/gemini-api/docs/oauth · https://ai.google.dev/gemini-api/docs/ephemeral-tokens · https://ai.google.dev/gemini-api/docs/api-versions · https://ai.google.dev/gemini-api/docs/available-regions · https://ai.google.dev/gemini-api/terms · https://ai.google.dev/gemini-api/docs/usage-policies · https://ai.google.dev/gemini-api/docs/zdr · https://ai.google.dev/gemini-api/docs/billing · discovery documents v1 / v1beta (revision 20260918)
Last verified: 2026-09-18 / 2026-09-19.
1. Base URLs
| Surface | URL |
|---|---|
| REST (beta, SDK default) | https://generativelanguage.googleapis.com/v1beta/… |
| REST (stable) | https://generativelanguage.googleapis.com/v1/… (v1alpha selectable in SDKs, undocumented) |
| Uploads / downloads | …/upload/v1beta/files, …/download/v1beta/files/{name}:download?alt=media |
| Live API | wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent |
| OpenAI-compatible | https://generativelanguage.googleapis.com/v1beta/openai/ |
2. Authentication
| Method | How | Notes |
|---|---|---|
| API key (header) — recommended | x-goog-api-key: $GEMINI_API_KEY |
used by SDKs (GEMINI_API_KEY / GOOGLE_API_KEY, the latter wins) and by this atlas |
| API key (query) — discouraged | ?key=… |
discovery doc: "Required unless you provide an OAuth 2.0 token"; leaks into logs/referrers; never used here |
| API key for OpenAI-compat | Authorization: Bearer $GEMINI_API_KEY |
mandatory on /v1beta/openai/*; x-goog-api-key alone → 400 INVALID_ARGUMENT "Missing or invalid Authorization header.", GET /openai/models → 404 (live) |
| OAuth 2.0 / ADC | Authorization: Bearer <access token> (gcloud ADC, desktop client, service account) |
stricter access control; required for owner-scoped resources (tuned models, corpora permissions); discovery auth.oauth2 only lists devstorage.read_only (media) — the generative-language scope is set up per the OAuth guide |
| Ephemeral tokens | POST /v1beta/auth_tokens → token used as if it were an API key by browser/mobile clients |
Live API (WebSocket) only; short-lived, use-limited |
| Vertex AI (Enterprise Agent Platform) | OAuth/ADC only, regional host | see vertex-vs-gemini-api |
Key types and hardening timeline
- Standard keys identify a project only. Authorization (auth) keys are bound to a service account (granular IAM, fast leaked-key enforcement) — default for all keys created in AI Studio since 2026-05-28.
- Unrestricted standard keys are already rejected; dormant unrestricted keys blocked since 2026-05-07; standard keys rejected from September 2026 → migrate (api-key.md "Migrate to an auth key").
- Leaked keys are auto-blocked:
Your API key was reported as leaked. Please use another API key. - Requests authenticated with auth keys are not recorded in service-account usage metrics.
- Limits: 10 projects created from AI Studio, 100 keys / 50 projects displayed; keys restricted to other APIs are hidden.
- IAM needed to create keys:
resourcemanager.projects.get,apikeys.keys.create,serviceusage.services.enable,iam.serviceAccounts.create,iam.serviceAccountApiKeyBindings.create.
3. Headers
Request
| Header / param | Required | Notes |
|---|---|---|
x-goog-api-key |
yes (native API) | see above |
Authorization: Bearer |
OpenAI-compat: yes; native: OAuth alternative | |
Content-Type: application/json |
JSON bodies | uploads use X-Goog-Upload-Protocol: resumable, `X-Goog-Upload-Command: start |
?alt=sse |
for SSE streaming | streamGenerateContent?alt=sse and interactions?alt=sse → text/event-stream; without it streamGenerateContent returns a JSON array |
x-goog-api-client |
no | SDK telemetry google-genai-sdk/2.24.0 gl-python/3.13 |
x-goog-user-project |
no | quota project when using OAuth user credentials (SDK option; generic Google header) |
X-Server-Timeout |
no | set by the SDK from http_options.timeout |
| No version header, no beta header | — | features are gated by the path version (/v1 vs /v1beta) only |
Response (observed 2026-09-19)
Content-Type: application/json; charset=UTF-8 · Server-Timing: gfet4t7; dur=<ms> · X-Gemini-Service-Tier: standard (undocumented, also on 429) · Alt-Svc, Vary, X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Accept-Ranges, Transfer-Encoding, Date, Server. OpenAI-compat adds Set-Cookie, Cache-Control, Expires, P3P. No x-ratelimit-*, Retry-After or request-id header — use responseId from the body.
4. API versions: v1 vs v1beta
| Feature (api-versions.md) | v1 | v1beta |
|---|---|---|
| Interactions API, function calling, structured output, thinking, system instructions | Yes | Yes |
| Audio output (speech config), service tier (priority/flex) | — | Yes |
| Code execution, Google Search, Google Maps, URL context, File Search | Yes | Yes |
| Computer Use tool, MCP servers tool | — | Yes |
| Live API, Live Music API, ephemeral tokens | — | Yes |
| Models API, Files, File Search stores | Yes | Yes |
| Agents API, Webhooks, Context caching (explicit) | — | Yes |
Discovery documents (rev. 20260918): v1beta = 86 methods, v1 = 47. Only in v1beta: cachedContents.*, tunedModels.* (incl. permissions, transferOwnership), corpora.* (+permissions), environments.*, auth_tokens.create, generatedFiles.list, models.predict / predictLongRunning, models.generateAnswer, PaLM legacy generateText, generateMessage, embedText, batchEmbedText, countTextTokens, countMessageTokens. Only in v1: media.download, operations.list/delete, tunedModels.operations.cancel. Both: models.list/get/generateContent/streamGenerateContent/countTokens/embedContent/batchEmbedContents/batchGenerateContent/asyncBatchEmbedContent, dynamic.generateContent, batches.*, files.*, fileSearchStores.*, media.upload(ToFileSearchStore).
Discrepancy: api-versions.md states "All models are supported in both v1 and v1beta", but live GET /v1/models returns 22 GA ids vs 58 in v1beta, and GET /v1/models/gemini-3.1-pro-preview → 404 Model is not found: models/gemini-3.1-pro-preview for api version v1. Preview, -latest, Live/TTS/transcribe, Veo, Lyria, Omni, robotics and aqa ids are v1beta-only. SDKs default to v1beta; set http_options.api_version='v1' / httpOptions.apiVersion for the stable surface.
5. Regions, terms, data use
- Regions: Gemini API and AI Studio available in ~190 countries/territories (available-regions.md; Colab uses the instance's region). Not available → use Gemini Enterprise Agent Platform. Age requirement 18+.
- EEA / UK / Switzerland: free and paid tiers are available to developers (billing FAQ), but API clients offered to end users there must use Paid Services only (terms §Use Restrictions); for EEA/CH/UK users the Paid Services data terms apply to all Services including AI Studio.
- Free tier data use: Unpaid Services — prompts, uploaded content and responses may be used "to provide, improve, and develop Google products", with human review; do not submit sensitive/confidential data. Paid Services: not used to improve products; prompts/responses logged for a limited period for abuse monitoring (usage-policies.md: 55 days).
- Zero data retention: not fully achievable on the Developer API — Search/Maps grounding store prompts/outputs 30 days (cannot be disabled); Interactions API stores state unless
store=false(incompatible withbackground=trueandprevious_interaction_id); guaranteed ZDR / DPA → Vertex AI. - Grounding with Google Search terms: display Grounded Results with Search Suggestions only to the requesting user in your own app; no caching, syndication, training on results.
- Billing is handled under Google Cloud terms (Cloud Billing account, prepay/postpay); AI Studio is free everywhere; Google AI Pro/Ultra subscriptions affect the AI Studio UI only, not API quotas.