Gemini Generate Content API Guide

Google Gemini is a very powerful AI conversational system that can generate fluent and natural responses within seconds by entering prompts. This document primarily describes how to use the Gemini Generate Content API, which is Google's official native API format and supports the generateContent and streamGenerateContent endpoints.

¶ Differences from the Chat Completions API

The Gemini Generate Content API uses Google's official native request format (the contents field), rather than the OpenAI-compatible format (the messages field). If you are already using the Google Gemini SDK or are familiar with the official API format, you can use this API directly without modifying the request format.

¶ Current Support Scope

The interface accepts text, image, video, and audio inputs (inlineData or fileData), thinking configuration, and custom function declarations. Native fields such as audio output, built-in tools, and explicit context caching do not yet have guaranteed unified availability; please refer to the actual response of the specific model.

When submitting audio and other files using fileData.fileUri, please ensure that the files can be accessed directly via HTTPS, do not depend on login state, and that the validity period of signed links covers the entire request processing time. Non-streaming audio analysis returns results only after the model completes processing, which may exceed 90 seconds; clients should set a sufficiently long total timeout based on file size and business scenarios to avoid disconnecting while the server is still processing.

¶ Application Process

Before using the Gemini Generate Content API, please first visit the Gemini Generate Content API page and click the "Get" button to obtain the credentials required for requests.

If you have not yet logged in or registered, you will be automatically redirected to the login page. The first application includes free quota.

¶ Basic Usage

¶ Non-Streaming

Send a POST request to /v1beta/models/{model}:generateContent:

Note: The flash models in the gemini-3.x series are thinking models and will consume reasoning tokens first; please set generationConfig.maxOutputTokens to 512 or above, otherwise only empty content may be returned.

curl -X POST "https://xapi.zhishuyun.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "你好，请介绍一下你自己"
          }
        ]
      }
    ]
  }'

Example response:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "你好！很高兴与你交流。"}]
      },
      "finishReason": "MAX_TOKENS"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 6,
    "candidatesTokenCount": 19,
    "thoughtsTokenCount": 489,
    "totalTokenCount": 514
  },
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 19,
    "total_tokens": 514,
    "thoughts_tokens": 489,
    "cost": {
      "amount": 0.008860916380159999,
      "currency": "credit",
      "list_amount": 0.009631430847999998
    }
  },
  "modelVersion": "gemini-3.5-flash",
  "model": "gemini-3.5-flash"
}

The token fields in usageMetadata are billed according to native Gemini semantics:

• promptTokenCount includes cachedContentTokenCount; cache-hit portions are calculated at the cached read price and are not counted again as regular input.
• promptTokensDetails and cacheTokensDetails are normalized into text_tokens, image_tokens, video_tokens, audio_tokens, and the corresponding cached_* details under usage.prompt_tokens_details. These values are included in prompt_tokens and cached_tokens respectively; different modalities are recalculated only at their respective prices and are not billed repeatedly.
• Both candidatesTokenCount and thoughtsTokenCount are calculated at the output token price.
• toolUsePromptTokenCount is an independent tool input token count, calculated at the input token price.

知数云 additionally returns a normalized usage object. Across model protocols, the cost of the current call is uniformly read from usage.cost. cost is an optional cost preview; when price previews are temporarily unavailable, the model response will still return normally, but may not include this field. The final bill is subject to usage records.

¶ Streaming

Send a POST request to /v1beta/models/{model}:streamGenerateContent?alt=sse:

curl -X POST "https://xapi.zhishuyun.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "写一首关于春天的诗"
          }
        ]
      }
    ]
  }'

Streaming responses gradually return content in SSE (Server-Sent Events) format. Intermediate events usually contain only incremental content; the final event containing authoritative usage includes usageMetadata and normalized usage, while the cost remains in usage.cost:

data: {"candidates":[{"content":{"parts":[{"text":"Hello!"}],"role":"model"},"index":0}],"modelVersion":"gemini-3.1-flash-lite","model":"gemini-3.1-flash-lite"}

data: {"candidates":[{"content":{"parts":[],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":7,"candidatesTokenCount":89,"totalTokenCount":96},"usage":{"prompt_tokens":7,"completion_tokens":89,"total_tokens":96,"cost":{"amount":0.00026161075472,"currency":"credit","list_amount":0.000284359516}},"modelVersion":"gemini-3.1-flash-lite","model":"gemini-3.1-flash-lite"}

Closing the connection indicates the end of the stream; native Gemini streams do not send data: [DONE]. If the final price preview is temporarily unavailable, usage will still return token usage, but will omit cost.

¶ Supported Models

¶ Advanced Features

¶ System Instructions

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "你好"}]
    }
  ],
  "systemInstruction": {
    "parts": [{"text": "你是一个专业的诗人，所有回复都用诗歌形式。"}]
  }
}

¶ Generation Configuration

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "讲一个故事"}]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 1024,
    "topP": 0.9,
    "topK": 40
  }
}

¶ JSON Mode

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "列出三个中国城市及其人口"}]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "city": {"type": "string"},
          "population": {"type": "integer"}
        }
      }
    }
  }
}

¶ Internal Thinking and Thinking Summaries

The model's internal thinking and returning thinking summaries to the caller are two independent settings:

• thinkingBudget or thinkingLevel controls the model's internal thinking budget or depth. The supported fields and values depend on the model.
• includeThoughts controls whether thinking summaries are returned, and defaults to false. When this field is omitted or false is passed, neither regular JSON nor SSE streaming responses return text marked as thought: true; such text is retained only when the boolean value true is explicitly passed.

When includeThoughts is not set in the request, the API passes false by default to generation models that support thinking configuration, avoiding unnecessary summaries; values explicitly passed by the client, thinking budgets, and levels are retained. The known model gemini-2.5-flash-image, which does not support thinking configuration, will not have this field added automatically, and generation configuration will not be added to countTokens requests either.

Disabling summaries does not mean disabling internal thinking, nor does it guarantee a reduction in internal thinking tokens. If the response still contains unrequested thinking text, the regular JSON and SSE outputs further filter it, retaining the normal answer, signatures, and actual usage.

When you need to view summaries, explicitly enable them as follows. If the model does not generate an available summary, there may still be no thinking text even when enabled:

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "解释量子纠缠"}]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "includeThoughts": true
    }
  }
}

thoughtSignature is encrypted state required for subsequent turns, not thinking summary text, and is not controlled by the includeThoughts switch. Signatures may be located on normal answers, function calls, or empty text Parts; when filtering thinking text, signatures and other fields in the same Part are retained, so the response may still contain Parts that carry only a signature and have empty text. When manually maintaining multi-turn history, retain the order of these Parts and the signature positions; do not move or merge signatures.

usageMetadata and usage still record actual usage. Hiding summaries does not reset thoughtsTokenCount, and billing is still calculated according to actual usage and current pricing rules.

See Google's official thinking and thinking summaries documentation and thinking signature rules.

¶ Function Calling

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "北京现在的天气怎么样？"}]
    }
  ],
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "获取指定城市的天气信息",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "城市名称"
              }
            },
            "required": ["city"]
          }
        }
      ]
    }
  ]
}

¶ Multi-turn Conversations

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "你好，我叫小明"}]
    },
    {
      "role": "model",
      "parts": [{"text": "你好小明！很高兴认识你。"}]
    },
    {
      "role": "user",
      "parts": [{"text": "我叫什么名字？"}]
    }
  ]
}

¶ Image Understanding

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "描述这张图片"},
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "base64_encoded_image_data..."
          }
        }
      ]
    }
  ]
}

¶ Safety Settings

Content filtering can be controlled through safetySettings:

{
  "contents": [...],
  "safetySettings": [
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "threshold": "BLOCK_ONLY_HIGH"
    }
  ]
}

¶ Error Handling