spb/doc-api

1[2 {"provider": "gemini", "name": "x-goog-api-key", "direction": "request", "required": "yes (unless Authorization or ?key=)", "description": "Gemini API key (AI Studio). Preferred way to authenticate the Gemini Developer API; used by the GenAI SDKs and this atlas. Standard keys are being replaced by authorization keys (bound to a service account); standard keys rejected from September 2026. Invalid/blocked keys -> 400 INVALID_ARGUMENT 'API key not valid' or 403 PERMISSION_DENIED; leaked keys -> 'Your API key was reported as leaked'.", "example": "x-goog-api-key: AIza...", "status": ["DOCUMENTED", "LIVE_VERIFIED"], "source": "https://ai.google.dev/gemini-api/docs/api-key"},3 {"provider": "gemini", "name": "key (query parameter)", "direction": "request", "required": "alternative to x-goog-api-key", "description": "`?key=API_KEY` query-string alternative documented in the discovery document ('Required unless you provide an OAuth 2.0 token'). Still shown in some REST reference snippets, but discouraged: keys end up in URLs, logs and referrers. Never used by this atlas.", "example": "GET /v1beta/models?key=AIza... (avoid)", "status": ["DOCUMENTED"], "source": "https://ai.google.dev/api/models"},4 {"provider": "gemini", "name": "Authorization", "direction": "request", "required": "OpenAI-compat: yes; native API: alternative", "description": "`Bearer <token>`. (1) OpenAI-compatibility layer (/v1beta/openai/*) REQUIRES the Gemini API key as `Authorization: Bearer <GEMINI_API_KEY>`; sending only x-goog-api-key returns 400 INVALID_ARGUMENT 'Missing or invalid Authorization header.' (live 2026-09-19). (2) Native API: OAuth 2.0 access token (user credentials or application-default credentials, scope generative-language) for stricter access control, tuned-model / corpora permissions; gcloud ADC flow documented in oauth.md.", "example": "Authorization: Bearer <api key | OAuth access token>", "status": ["DOCUMENTED", "LIVE_VERIFIED"], "source": "https://ai.google.dev/gemini-api/docs/openai"},5 {"provider": "gemini", "name": "x-goog-user-project", "direction": "request", "required": "no", "description": "Standard Google API header naming the Cloud project billed/quota-charged when authenticating with OAuth user credentials instead of an API key. Sent by the google-genai SDK when configured; not mentioned in Gemini docs pages.", "example": "x-goog-user-project: my-project-id", "status": ["UNVERIFIED"], "source": "https://cloud.google.com/docs/authentication/rest#set-billing-project"},6 {"provider": "gemini", "name": "Content-Type", "direction": "request", "required": "yes for JSON bodies", "description": "`application/json` for all JSON methods. Resumable media upload uses `X-Goog-Upload-*` headers instead. The Batch API JSONL upload uses mime type `jsonl`.", "example": "Content-Type: application/json", "status": ["DOCUMENTED", "LIVE_VERIFIED"], "source": "https://ai.google.dev/gemini-api/docs/quickstart"},7 {"provider": "gemini", "name": "alt (query parameter)", "direction": "request", "required": "for SSE streaming", "description": "`?alt=sse` switches streamGenerateContent / interactions streaming to Server-Sent Events (`text/event-stream`, `data: {...}` lines). Without it streamGenerateContent returns a JSON array of chunks. Discovery doc also lists alt=json|media|proto.", "example": "POST /v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse", "status": ["DOCUMENTED"], "source": "https://ai.google.dev/gemini-api/docs/text-generation"},8 {"provider": "gemini", "name": "x-goog-api-client", "direction": "request", "required": "no (SDK telemetry)", "description": "Client library identifier sent by the GenAI SDKs, e.g. `google-genai-sdk/2.24.0 gl-python/3.13` (Python) or `google-genai-sdk/2.23.0 gl-node/...` (JS). Not required for raw REST calls.", "example": "x-goog-api-client: google-genai-sdk/2.24.0 gl-python/3.13", "status": ["DOCUMENTED"], "source": "https://github.com/googleapis/python-genai (_api_client.py)"},9 {"provider": "gemini", "name": "X-Server-Timeout", "direction": "request", "required": "no", "description": "Server-side timeout hint (seconds) set by the google-genai SDK from `http_options.timeout` (SDK code); relevant for long Flex / Deep Research requests.", "example": "X-Server-Timeout: 600", "status": ["UNVERIFIED"], "source": "https://github.com/googleapis/python-genai (_api_client.py)"},10 {"provider": "gemini", "name": "X-Goog-Upload-Protocol / X-Goog-Upload-Command / X-Goog-Upload-Header-Content-Length / X-Goog-Upload-Header-Content-Type / X-Goog-Upload-Offset", "direction": "request", "required": "for resumable uploads", "description": "Resumable upload protocol on /upload/v1beta/files and /upload/v1beta/fileSearchStores/{store}:uploadToFileSearchStore: start with `X-Goog-Upload-Protocol: resumable`, `X-Goog-Upload-Command: start`, then `upload, finalize` to the `x-goog-upload-url` returned in the response headers.", "example": "X-Goog-Upload-Protocol: resumable", "status": ["DOCUMENTED"], "source": "https://ai.google.dev/gemini-api/docs/file-search"},11 {"provider": "gemini", "name": "x-goog-upload-url", "direction": "response", "required": null, "description": "Returned by the resumable-upload `start` request; subsequent upload/finalize chunks are sent to this URL.", "example": "x-goog-upload-url: https://generativelanguage.googleapis.com/upload/v1beta/files?upload_id=...", "status": ["DOCUMENTED"], "source": "https://ai.google.dev/gemini-api/docs/files"},12 {"provider": "gemini", "name": "X-Gemini-Service-Tier", "direction": "response", "required": null, "description": "Undocumented response header observed on every native generateContent response (200 and 429): the service tier that handled the request; mirrors `usageMetadata.serviceTier`. Absent on the OpenAI-compat endpoint.", "example": "X-Gemini-Service-Tier: standard", "status": ["LIVE_DISCOVERED"], "source": "live probe 2026-09-19 (tmp-live/gemini-models-probe.json)"},13 {"provider": "gemini", "name": "Server-Timing", "direction": "response", "required": null, "description": "Google front-end timing, e.g. `gfet4t7; dur=87` (ms). Only timing header present; no request-id header is returned (use `responseId` in the JSON body).", "example": "Server-Timing: gfet4t7; dur=87", "status": ["LIVE_DISCOVERED"], "source": "live probe 2026-09-19"},14 {"provider": "gemini", "name": "x-ratelimit-* / Retry-After", "direction": "response", "required": null, "description": "NOT exposed. Neither the docs nor live responses (200/404/429) carry rate-limit remaining/reset headers or Retry-After; the retry delay is embedded in the 429 message text ('Please retry in 54.2s').", "example": "(absent)", "status": ["LIVE_DISCOVERED"], "source": "live probe 2026-09-19"},15 {"provider": "gemini", "name": "Content-Type", "direction": "response", "required": null, "description": "`application/json; charset=UTF-8` for JSON; `text/event-stream` with alt=sse; media downloads via /download/v1beta/files/{name}:download return the file's mime type.", "example": "Content-Type: application/json; charset=UTF-8", "status": ["LIVE_VERIFIED"], "source": "live probe 2026-09-19"},16 {"provider": "gemini", "name": "Set-Cookie / P3P / Cache-Control / Expires", "direction": "response", "required": null, "description": "Present only on the OpenAI-compatibility endpoints (/v1beta/openai/*), which are served by a different front end; harmless but note when comparing raw responses.", "example": "Cache-Control: private", "status": ["LIVE_DISCOVERED"], "source": "live probe 2026-09-19"},17 {"provider": "gemini", "name": "Vertex-style headers (not applicable)", "direction": "request", "required": "no", "description": "The Gemini Developer API has no API-version header (version is in the URL path /v1 or /v1beta) and no beta-feature header; features are gated by path version only. Gemini Enterprise Agent Platform (Vertex AI) instead uses OAuth/ADC `Authorization: Bearer` with regional hosts `https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/publishers/google/models/{model}:generateContent`.", "example": "(none)", "status": ["DOCUMENTED"], "source": "https://ai.google.dev/gemini-api/docs/api-versions"}18]19