# 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](vertex-vs-gemini-api.md) |

### 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|upload, finalize`, `X-Goog-Upload-Header-Content-Length/-Type`, `X-Goog-Upload-Offset` and the returned `x-goog-upload-url` |
| `?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 with `background=true` and `previous_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.