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.
`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.

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": "google/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 the SDK alias 512 and normalizes it to 0.5K; 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.

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.