# Gemini models.generateContent — exhaustive reference

Status: DOCUMENTED + LIVE_VERIFIED (190-call probe on gemini-3.5-flash-lite / gemini-3.5-flash / gemini-3.8-flash, 2026-09-18, est. $0.0045, free-tier key; raws in tmp-live/gemini-core/). Explicit caching and gemini-3.1-pro-preview probes are ACCOUNT_RESTRICTED on this key. Sources: https://ai.google.dev/api/generate-content · https://ai.google.dev/gemini-api/docs/generate-content/text-generation · https://ai.google.dev/gemini-api/docs/generate-content/gemini-3 · https://ai.google.dev/gemini-api/docs/generate-content/whats-new-gemini-3.5 · https://ai.google.dev/gemini-api/docs/api-versions · discovery https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta (rev. 20260918) Machine-readable: generated/fragments/endpoints/gemini-core.json, generated/fragments/parameters/gemini-generate-content.json (68 records), generated/fragments/objects/gemini-core-objects.json, generated/fragments/streaming-events/gemini-core.json, generated/fragments/compatibility/gemini-feature-model-matrix.json Last verified: 2026-09-18

# 1. Request

POST https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
x-goog-api-key: <key>          (never put the key in the URL; `?key=` works but leaks)
Content-Type: application/json

• Also: /v1/models/{model}:generateContent (stable; identical shape, verified), tunedModels/{id}:generateContent (tuning domain), dynamic/{id}:generateContent (discovery only — both probed ids → 404, purpose unknown).
• Field names: camelCase and snake_case are interchangeable on the wire (system_instruction, generation_config.max_output_tokens verified).
• Unknown fields → 400 INVALID_ARGUMENT "Invalid JSON payload received. Unknown name \"x\" at 'generation_config': Cannot find field." with a google.rpc.BadRequest.fieldViolations detail.
• Method must be POST: GET …:generateContent → 404 with an empty body.

# 1.1 Body (GenerateContentRequest)

# 1.2 Parts

# 1.3 generationConfig — every field

# 2. Response (GenerateContentResponse)

{
  "candidates": [{"content": {"parts": [{"text": "OK", "thoughtSignature": "El4KXAFpFH0T…"}], "role": "model"}, "finishReason": "STOP", "index": 0}],
  "usageMetadata": {"promptTokenCount": 5, "candidatesTokenCount": 1, "totalTokenCount": 6,
                    "promptTokensDetails": [{"modality": "TEXT", "tokenCount": 5}], "serviceTier": "standard"},
  "modelVersion": "gemini-3.5-flash-lite",
  "responseId": "ZgWuapkcpuD-4w_B5sz4CQ"
}

• candidates[] — absent only when the prompt is blocked (promptFeedback.blockReason). Each: content, finishReason, finishMessage?, index, safetyRatings? (only when safetySettings were sent), citationMetadata?, groundingMetadata?, urlContextMetadata?, logprobsResult?, avgLogprobs?, tokenCount?.
• finishReason enum (discovery 20260918): STOP, MAX_TOKENS, SAFETY, RECITATION, LANGUAGE, OTHER, BLOCKLIST, PROHIBITED_CONTENT, SPII, MALFORMED_FUNCTION_CALL, IMAGE_SAFETY, IMAGE_PROHIBITED_CONTENT, IMAGE_OTHER, NO_IMAGE, IMAGE_RECITATION, UNEXPECTED_TOOL_CALL, TOO_MANY_TOOL_CALLS, MISSING_THOUGHT_SIGNATURE, MALFORMED_RESPONSE, ESCALATION, PUP_LIMITED_DISABLED.
• usageMetadata: promptTokenCount (includes cached tokens), cachedContentTokenCount, candidatesTokenCount (absent when only thoughts were produced), thoughtsTokenCount, toolUsePromptTokenCount, totalTokenCount, promptTokensDetails[]/cacheTokensDetails[]/candidatesTokensDetails[]/toolUsePromptTokensDetails[] ({modality: TEXT|IMAGE|VIDEO|AUDIO|DOCUMENT, tokenCount}), serviceTier (observed on every 200: standard, flex when requested).
• modelVersion = model id (gemini-3.5-flash-lite), while models.get(...).version is 3.5-flash-lite-07-2026. responseId opaque. modelStatus ({modelStage, retirementTime, message}) documented in discovery, never observed.
• No rate-limit or request-id headers are returned (only Server-Timing: gfet4t7; dur=…).

# 3. Errors (observed)

Envelope: {"error": {"code": <http>, "message": "...", "status": "<google.rpc.Code>", "details": [...]}}.

# 4. SDK mapping

• Python google-genai 2.24: client.models.generate_content(model=, contents=, config=types.GenerateContentConfig(system_instruction=, temperature=, max_output_tokens=, response_mime_type=, response_json_schema=, thinking_config=, safety_settings=, cached_content=, labels=, service_tier=, http_options=types.HttpOptions(api_version=, timeout=, headers=, base_url=, retry_options=))). http_options is client-side only (not on the wire). response.text concatenates non-thought text parts.
• Node @google/genai 2.23: ai.models.generateContent({model, contents, config}) — same config keys in camelCase.
• Known SDK-vs-REST gaps (verified): both SDKs refuse system_instruction/tools in count_tokens for the Developer API ("only supported in Gemini Enterprise Agent Platform mode") although REST accepts them via generateContentRequest; SDK-only config fields (audio_timestamp, model_selection_config, routing_config, model_armor_config, SafetySetting.method) are Vertex-only and rejected on the wire (Unknown name).
• REST examples: examples/gemini/generate-content/.

# 5. Related pages

docs/gemini/streaming.md · structured-outputs.md · thinking.md · safety.md · context-caching.md · files.md · multimodal-input.md · token-counting.md · embeddings.md · legacy-palm-methods.md