Gemini Generate Content

Endpoints

POST /v1/models/{model}:generateContent
POST /v1beta/models/{model}:generateContent
POST /v1/models/{model}:streamGenerateContent
POST /v1beta/models/{model}:streamGenerateContent

{model} is the complete public model ID and can contain /, for example google/gemini-2.5-flash. Both version prefixes use the same gateway behavior. The action suffix selects synchronous or streaming delivery.

Authenticate with x-goog-api-key: $API_KEY, Authorization: Bearer $API_KEY, or the key query parameter.

Request body

Field	Type	Required	Description
`contents`	array	Yes	Non-empty Gemini content history.
`systemInstruction`	object	No	System instruction with `parts`.
`generationConfig`	object	No	Output, sampling, response, and media configuration.
`generationConfig.maxOutputTokens`	integer	No	Maximum generated tokens.
`generationConfig.temperature`	number	No	Sampling temperature.
`generationConfig.topP`	number	No	Nucleus sampling value.
`generationConfig.stopSequences`	string[]	No	Stop sequences.
`generationConfig.thinkingConfig.thinkingLevel`	string	No	Reasoning depth. Gemini 4 Argon accepts `low`, `medium` (default), or `high`; `minimal` is not supported. Do not send it together with `thinkingBudget`.
`tools`	array	No	Gemini tool declarations, including `functionDeclarations`, code execution, and supported native tools.
`toolConfig`	object	No	Function-calling mode and allowed function names.
`safetySettings`	array	No	Per-category content safety thresholds on same-protocol routes.
`cachedContent`	string	No	Gemini cached-content resource name on same-protocol routes.
`store`	boolean	No	Gemini request-logging preference on same-protocol routes.
`continuationToken`	string	No	Gemini 4 Argon long-decode continuation. Send only the latest token from the previous response.

Each content item contains a role and parts. Common parts include text, inlineData, functionCall, and functionResponse. The selected model determines supported modalities and tool features.

Synchronous text example

curl "http://127.0.0.1:11113/v1beta/models/google/gemini-2.5-flash:generateContent" -H "x-goog-api-key: $API_KEY" -H "Content-Type: application/json" -d '{
  "contents": [
    {"role": "user", "parts": [{"text": "Explain model gateways briefly."}]}
  ],
  "generationConfig": {"maxOutputTokens": 256}
}'

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{ "text": "A model gateway unifies access to multiple AI models." }]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 12,
    "totalTokenCount": 20
  },
  "modelVersion": "gemini-2.5-flash"
}

Streaming

Call :streamGenerateContent to receive data-only SSE chunks. Each event contains a Gemini GenerateContentResponse. There is no [DONE] marker; finish after the final candidate with finishReason and final usageMetadata, or when the connection closes cleanly.

curl -N "http://127.0.0.1:11113/v1beta/models/google/gemini-2.5-flash:streamGenerateContent" -H "x-goog-api-key: $API_KEY" -H "Content-Type: application/json" -d '{"contents":[{"role":"user","parts":[{"text":"Count to three."}]}]}'

Gemini image output

Gemini-native image models use the same Generate Content endpoints, not /v1/images/*. Request image output through generationConfig, and read generated image bytes from candidate inlineData parts.

{
  "contents": [
    { "role": "user", "parts": [{ "text": "Create a minimal cloud icon." }] }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "imageSize": "1K",
      "aspectRatio": "1:1"
    }
  }
}

Supported image-size tiers are model-specific. The gateway accepts both 0.5K and the official 512 value (normalizing outbound requests to 512); other common tiers are 1K, 2K, and 4K. Generated and input base64 data is preserved in transit but replaced by size placeholders in stored logs.

Gemini 4 Argon long decoding

google/gemini-4-argon can produce output longer than one request allows. Set generationConfig.maxOutputTokens to the total budget for the whole task, above 65,536 and at most 1,048,576 minus the input tokens. A single request returns about 64K output tokens when streaming and about 32K when not streaming.

When a response ends with finishReason: "CONTINUATION" and a candidates[].continuationToken, resend the same request unchanged, with the latest token added at the top level as continuationToken. Repeat until finishReason is no longer CONTINUATION. Concatenate the parts of each hop in order. Do not append partial output to contents.

Each hop is a separate request with its own billing, and its usage comes from that response's usageMetadata. For long tasks, use streaming and set the client read timeout to 20 minutes. The official service closes non-streaming connections after 10 minutes and streaming connections after 20 minutes.

Cross-protocol routes (OpenAI- and Anthropic-compatible endpoints) do not support long decoding.

The second hop of a streaming task:

curl -N "http://127.0.0.1:11113/v1beta/models/google/gemini-4-argon:streamGenerateContent" -H "x-goog-api-key: $API_KEY" -H "Content-Type: application/json" -d '{
  "contents": [
    {"role": "user", "parts": [{"text": "Write a long technical report."}]}
  ],
  "generationConfig": {"maxOutputTokens": 200000},
  "continuationToken": "<continuationToken from the previous hop>"
}'

Protocol conversion

Same-protocol routes preserve Gemini fields and opaque thoughtSignature values. For cross-protocol routes, the gateway maps text and inline images, system instructions, function calls and results, function declarations, tool mode, common generation settings, stream chunks, finish reasons, and usage. Gemini-only fields such as safetySettings or cachedContent can be omitted and reported through x-dropped-params.

Client routing fields and paid service tiers are rejected. A missing or empty contents array returns 400 INVALID_ARGUMENT with gateway code invalid_request in the message.