生成文本回复（支持流式）

调用方式	请求地址	响应 Content-Type	客户端处理方式
非流式	`/v1beta/models/{model}:generateContent`	`application/json`	等待生成完成后解析一个完整的 `GeminiChatResponse`。
流式	`/v1beta/models/{model}:generateContent?alt=sse`	`text/event-stream`	按 SSE 事件逐条读取并解析每个 `data:` 后面的 `GeminiChatResponse` JSON。

流式请求示例：

流式响应的每个事件格式如下：

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"第一段文本"}]},"index":0}]}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"第二段文本"}]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12,"candidatesTokenCount":8,"totalTokenCount":20}}

客户端应当：

按空行分隔 SSE 事件；

去掉每条事件开头的 data: 后解析 JSON；

按顺序读取 candidates[].content.parts[].text；

以连接正常结束作为流结束依据，不要依赖 OpenAI 格式的 [DONE]；

使用最后一个包含完整 usageMetadata 的事件进行用量记录和账单核对。

2. 计费原理与计算口径

一次文本对话可能同时包含普通文本/图片/视频输入、音频输入、缓存命中、
文本输出和思考 Token。不同类别可能使用不同单价，因此不能直接使用
totalTokenCount × 一个统一单价 计算费用。

流式与非流式使用相同计费规则。流式过程中不得把多个事件里的 Token 统计相加；
应使用最后一个包含完整 usageMetadata 的事件作为本次请求的最终用量。

接口只返回 usageMetadata 用量，不返回价格版本、币种或本次最终金额。
以下费率用于说明字段映射和计算方法；实际生效价格、模型名称、倍率、折扣和结算金额
以服务平台提供的报价及账单为准。

2.1 常规上下文模型参考费率

单价单位均为 USD/100 万 Token；缓存存储单位为 USD/100 万 Token·小时。

价格系列	请求模型示例	普通输入（文本/图片/视频）	音频输入	缓存命中（普通输入）	缓存命中（音频）	缓存存储	文本/思考输出
Gemini 2.5 Flash	`gemini-2.5-flash`	0.30	1.00	0.030	0.100	1.00	2.50
Gemini 2.5 Flash-Lite	`gemini-2.5-flash-lite`	0.10	0.30	0.010	0.030	1.00	0.40
Gemini 3 Flash	`gemini-3-flash-preview`	0.50	1.00	0.050	0.100	1.00	3.00
Gemini 3.1 Flash-Lite	`gemini-3.1-flash-lite`	0.25	0.50	0.025	0.050	1.00	1.50
Gemini 3.5 Flash	`gemini-3.5-flash`	1.50	1.50	0.150	0.150	1.00	9.00

2.2 长上下文阶梯模型参考费率

阶梯判断使用本次输入上下文长度：

LEN = promptTokenCount + toolUsePromptTokenCount

价格系列	请求模型示例	LEN	输入	缓存命中	缓存存储	文本/思考输出
Gemini 2.5 Pro	`gemini-2.5-pro`	≤ 200,000	1.25	0.125	4.50	10.00
Gemini 2.5 Pro	`gemini-2.5-pro`	> 200,000	2.50	0.250	4.50	15.00
Gemini 3.1 Pro	`gemini-3.1-pro-preview`	≤ 200,000	2.00	0.200	4.50	12.00
Gemini 3.1 Pro	`gemini-3.1-pro-preview`	> 200,000	4.00	0.400	4.50	18.00

2.3 用量字段与互斥计费桶

P_TOTAL = promptTokenCount + toolUsePromptTokenCount
P_AUDIO = promptTokensDetails[AUDIO] + toolUsePromptTokensDetails[AUDIO]
P_OTHER = max(P_TOTAL - P_AUDIO, 0)

C_TOTAL = cachedContentTokenCount
C_AUDIO = cacheTokensDetails[AUDIO]
C_OTHER = max(C_TOTAL - C_AUDIO, 0)

U_AUDIO = max(P_AUDIO - C_AUDIO, 0)
U_OTHER = max(P_OTHER - C_OTHER, 0)

O_TEXT = candidatesTokenCount
O_THOUGHT = thoughtsTokenCount

promptTokenCount 已经包含缓存命中 Token，P_AUDIO 也已经包含缓存音频 Token。
因此缓存桶必须先从普通输入桶中扣除，不能重复相加。

常规上下文模型的单次请求费用：

普通输入费用
  = U_OTHER × 普通输入单价 ÷ 1,000,000
  + U_AUDIO × 音频输入单价 ÷ 1,000,000

缓存命中费用
  = C_OTHER × 普通缓存单价 ÷ 1,000,000
  + C_AUDIO × 音频缓存单价 ÷ 1,000,000

文本/思考输出费用
  = (O_TEXT + O_THOUGHT) × 输出单价 ÷ 1,000,000

请求总费用
  = 普通输入费用 + 缓存命中费用 + 文本/思考输出费用

长上下文阶梯模型先使用 LEN 选择整次请求的价格档位，再计算：

U = max(P_TOTAL - C_TOTAL, 0)
C = C_TOTAL
O = candidatesTokenCount + thoughtsTokenCount

请求总费用
  = (U × 当前档位输入单价
     + C × 当前档位缓存单价
     + O × 当前档位输出单价)
    ÷ 1,000,000

缓存存储费不是单次 generateContent 响应费用。若客户另外创建了缓存资源，
存储费用通常按“缓存 Token × 存储小时数”计算：

缓存存储费用
  = 缓存资源 Token × 缓存存储单价 × 存储小时数 ÷ 1,000,000

本接口响应无法单独确定缓存资源存储了多少小时，因此缓存存储费应从缓存资源记录或平台账单核对。

3. Gemini 响应字段逐项说明

3.1 响应顶层字段

字段	类型	说明
`candidates`	array	候选回复列表。通常读取索引 0，但客户端应允许多个候选。
`promptFeedback`	object	整个输入提示的安全反馈。输入被拦截时可能没有 `candidates`。
`usageMetadata`	object	本次请求的 Token 用量，是费用预估和账单核对的核心对象。
`modelVersion`	string	上游实际执行请求的模型版本，建议与请求模型一起保存。
`responseId`	string	上游响应 ID，用于请求定位和账单核对。

3.2 `candidates[]` 字段

字段	类型	说明
`candidates[].index`	integer	候选序号，通常从 0 开始。
`candidates[].content`	object	当前候选的输出内容。
`candidates[].finishReason`	string	结束原因。`STOP` 通常表示正常完成；`MAX_TOKENS` 表示达到输出限制；`SAFETY` 表示内容被安全策略终止。
`candidates[].finishMessage`	string	对结束原因的可读补充说明，可能缺失。
`candidates[].safetyRatings`	array	当前候选的安全分类和风险概率。

3.3 `content` 和 `parts[]` 字段

字段	类型	说明
`content.role`	string	输出角色，通常为 `model`。
`content.parts`	array	输出片段列表，可能包含文本、思考摘要或函数调用。
`parts[].text`	string	普通文本回复；当 `thought=true` 时表示可返回的思考摘要。
`parts[].thought`	boolean	当前 Part 是否为思考内容。
`parts[].thoughtSignature`	string	多轮对话或函数调用时可能需要原样回传的不透明签名。
`parts[].functionCall.name`	string	模型希望调用的函数名称。
`parts[].functionCall.args`	object	模型生成的函数参数。
`parts[].inlineData`	object	模型返回的内联媒体；纯文本模型通常不会返回。
`parts[].executableCode`	object	可选的模型生成代码。
`parts[].codeExecutionResult`	object	可选的代码执行结果。

3.4 `promptFeedback` 和安全字段

字段	类型	说明
`promptFeedback.blockReason`	string	输入被拦截的原因，例如 `SAFETY`、`BLOCKLIST` 或 `PROHIBITED_CONTENT`。
`promptFeedback.safetyRatings`	array	输入提示的安全评估列表。
`safetyRatings[].category`	string	被评估的安全类别。
`safetyRatings[].probability`	string	风险概率，例如 `NEGLIGIBLE`、`LOW`、`MEDIUM`、`HIGH`。
`safetyRatings[].blocked`	boolean	是否因为该安全类别而被拦截。

3.5 `usageMetadata` 字段

字段	类型	计费含义
`promptTokenCount`	integer	输入提示总 Token，包含文本、图片、视频、音频和缓存命中用量。
`toolUsePromptTokenCount`	integer	工具相关提示 Token，应加入输入总量。
`cachedContentTokenCount`	integer	缓存命中总 Token，是输入总量的子集。
`candidatesTokenCount`	integer	候选输出 Token，不包含 `thoughtsTokenCount`。
`thoughtsTokenCount`	integer	思考 Token，按文本/思考输出单价计费。
`totalTokenCount`	integer	总 Token 核验字段，不能直接乘以单一价格计算精确金额。
`promptTokensDetails`	array	输入提示按 `TEXT`、`IMAGE`、`VIDEO`、`AUDIO` 等模态拆分。
`toolUsePromptTokensDetails`	array	工具提示按模态拆分。
`cacheTokensDetails`	array	缓存命中按模态拆分，是输入 Token 的子集。
`candidatesTokensDetails`	array	候选输出按模态拆分；文本对话通常为 `TEXT`。
`serviceTier`	string	上游实际服务层级，可能缺失；最终计费仍以平台有效价格为准。
`*TokensDetails[].modality`	string	Token 模态，例如 `TEXT`、`IMAGE`、`VIDEO`、`AUDIO`。
`*TokensDetails[].tokenCount`	integer	对应模态的 Token 数量。

客户侧建议保存请求模型、modelVersion、responseId、完整 usageMetadata、
使用的价格版本、匹配的上下文档位和计算金额，便于后续核对。

4. 典型场景与计费示例

以下金额仅用于展示如何从 Gemini Response JSON 读取字段并计算费用。

场景一：`gemini-2.5-flash`，音频输入并命中缓存

示例响应：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "会议主要讨论了产品发布计划、风险事项和后续负责人。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 100000,
    "toolUsePromptTokenCount": 0,
    "cachedContentTokenCount": 30000,
    "candidatesTokenCount": 1000,
    "thoughtsTokenCount": 500,
    "totalTokenCount": 101500,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 60000
      },
      {
        "modality": "AUDIO",
        "tokenCount": 40000
      }
    ],
    "cacheTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 20000
      },
      {
        "modality": "AUDIO",
        "tokenCount": 10000
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 1000
      }
    ]
  },
  "modelVersion": "gemini-2.5-flash",
  "responseId": "response-chat-example-001"
}

字段解释：

普通输入总量为 60,000 Token，其中普通缓存命中为 20,000。

音频输入总量为 40,000 Token，其中音频缓存命中为 10,000。

因此普通非缓存输入为 40,000，音频非缓存输入为 30,000。

文本输出为 1,000 Token，思考输出为 500 Token。

普通非缓存输入费用
  = 40,000 × USD 0.30 ÷ 1,000,000
  = USD 0.01200

音频非缓存输入费用
  = 30,000 × USD 1.00 ÷ 1,000,000
  = USD 0.03000

普通缓存命中费用
  = 20,000 × USD 0.030 ÷ 1,000,000
  = USD 0.00060

音频缓存命中费用
  = 10,000 × USD 0.100 ÷ 1,000,000
  = USD 0.00100

文本/思考输出费用
  = (1,000 + 500) × USD 2.50 ÷ 1,000,000
  = USD 0.00375

请求总费用
  = USD 0.01200 + USD 0.03000 + USD 0.00060
    + USD 0.00100 + USD 0.00375
  = USD 0.04735

场景二：`gemini-2.5-pro`，输入超过 20 万 Token

示例响应：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "以下是对长文档的风险分析、结论和建议。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 250000,
    "toolUsePromptTokenCount": 0,
    "cachedContentTokenCount": 50000,
    "candidatesTokenCount": 4000,
    "thoughtsTokenCount": 1000,
    "totalTokenCount": 255000,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 250000
      }
    ],
    "cacheTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 50000
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 4000
      }
    ]
  },
  "modelVersion": "gemini-2.5-pro",
  "responseId": "response-chat-example-002"
}

字段解释：

LEN=250000，超过 200,000，因此整次请求使用长上下文档位。

输入总量为 250,000，其中缓存命中 50,000，非缓存输入为 200,000。

输出总量为 4000 + 1000 = 5000 Token。

非缓存输入费用
  = 200,000 × USD 2.50 ÷ 1,000,000
  = USD 0.50000

缓存命中费用
  = 50,000 × USD 0.250 ÷ 1,000,000
  = USD 0.01250

文本/思考输出费用
  = (4,000 + 1,000) × USD 15.00 ÷ 1,000,000
  = USD 0.07500

请求总费用
  = USD 0.50000 + USD 0.01250 + USD 0.07500
  = USD 0.58750

场景三：`gemini-3.1-pro-preview`，输入不超过 20 万 Token

示例响应：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "这是基于材料生成的结构化决策建议。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 100000,
    "toolUsePromptTokenCount": 0,
    "cachedContentTokenCount": 20000,
    "candidatesTokenCount": 2000,
    "thoughtsTokenCount": 1000,
    "totalTokenCount": 103000,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 100000
      }
    ],
    "cacheTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 20000
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 2000
      }
    ]
  },
  "modelVersion": "gemini-3.1-pro-preview",
  "responseId": "response-chat-example-003"
}

字段解释：

LEN=100000，不超过 200,000，因此使用标准上下文档位。

输入总量为 100,000，其中缓存命中 20,000，非缓存输入为 80,000。

输出总量为 2000 + 1000 = 3000 Token。

非缓存输入费用
  = 80,000 × USD 2.00 ÷ 1,000,000
  = USD 0.16000

缓存命中费用
  = 20,000 × USD 0.200 ÷ 1,000,000
  = USD 0.00400

文本/思考输出费用
  = (2,000 + 1,000) × USD 12.00 ÷ 1,000,000
  = USD 0.03600

请求总费用
  = USD 0.16000 + USD 0.00400 + USD 0.03600
  = USD 0.20000

Bearer Token

在 Header 添加参数

Authorization

，其值为在 Bearer 之后拼接 Token

示例：

Authorization: Bearer ********************

API Key

在 header 添加参数

x-goog-api-key

示例：

x-goog-api-key: ********************

API Key

在 query 添加参数

key

示例：

key: ********************

application/json

请求成功。未传 alt 时返回一个完整 JSON；传入 alt=sse 时返回 SSE 事件流。
响应可能包含文本、思考摘要、函数调用、用量信息或安全反馈。

Body

示例

文本回复和完整用量模型请求调用函数输入被安全策略拦截

{
    "candidates": [
        {
            "content": {
                "role": "model",
                "parts": [
                    {
                        "text": "北京是中国的首都。"
                    }
                ]
            },
            "finishReason": "STOP",
            "index": 0,
            "safetyRatings": []
        }
    ],
    "usageMetadata": {
        "promptTokenCount": 12,
        "toolUsePromptTokenCount": 0,
        "cachedContentTokenCount": 0,
        "candidatesTokenCount": 8,
        "thoughtsTokenCount": 0,
        "totalTokenCount": 20,
        "promptTokensDetails": [
            {
                "modality": "TEXT",
                "tokenCount": 12
            }
        ],
        "candidatesTokensDetails": [
            {
                "modality": "TEXT",
                "tokenCount": 8
            }
        ]
    },
    "modelVersion": "gemini-2.5-flash",
    "responseId": "response-example-id"
}

生成文本回复（支持流式）

前置阅读

1. 接口说明

1.1 非流式与流式调用

2. 计费原理与计算口径

2.1 常规上下文模型参考费率

2.2 长上下文阶梯模型参考费率

2.3 用量字段与互斥计费桶

3. Gemini 响应字段逐项说明

3.1 响应顶层字段

3.2 `candidates[]` 字段

3.3 `content` 和 `parts[]` 字段

3.4 `promptFeedback` 和安全字段

3.5 `usageMetadata` 字段

4. 典型场景与计费示例

场景一：`gemini-2.5-flash`，音频输入并命中缓存

场景二：`gemini-2.5-pro`，输入超过 20 万 Token

场景三：`gemini-3.1-pro-preview`，输入不超过 20 万 Token

请求参数

请求示例代码

返回响应

生成文本回复（支持流式）

前置阅读#

1. 接口说明#

1.1 非流式与流式调用#

2. 计费原理与计算口径#

2.1 常规上下文模型参考费率#

2.2 长上下文阶梯模型参考费率#

2.3 用量字段与互斥计费桶#

3. Gemini 响应字段逐项说明#

3.1 响应顶层字段#

3.2 candidates[] 字段#

3.3 content 和 parts[] 字段#

3.4 promptFeedback 和安全字段#

3.5 usageMetadata 字段#

4. 典型场景与计费示例#

场景一：gemini-2.5-flash，音频输入并命中缓存#

场景二：gemini-2.5-pro，输入超过 20 万 Token#

场景三：gemini-3.1-pro-preview，输入不超过 20 万 Token#

请求参数

请求示例代码

返回响应

前置阅读

1. 接口说明

1.1 非流式与流式调用

2. 计费原理与计算口径

2.1 常规上下文模型参考费率

2.2 长上下文阶梯模型参考费率

2.3 用量字段与互斥计费桶

3. Gemini 响应字段逐项说明

3.1 响应顶层字段

3.2 `candidates[]` 字段

3.3 `content` 和 `parts[]` 字段

3.4 `promptFeedback` 和安全字段

3.5 `usageMetadata` 字段

4. 典型场景与计费示例

场景一：`gemini-2.5-flash`，音频输入并命中缓存

场景二：`gemini-2.5-pro`，输入超过 20 万 Token

场景三：`gemini-3.1-pro-preview`，输入不超过 20 万 Token