原生Gemini格式

模型	输入	文本/思考输出	图片输出	图片计费方式
`gemini-2.5-flash-image`	USD 0.30/100 万 Token	USD 2.50/100 万 Token	USD 0.039/张	按实际返回图片张数
`gemini-3-pro-image`	USD 2.00/100 万 Token	USD 12.00/100 万 Token	USD 120.00/100 万图片 Token	按图片 Token
`gemini-3.1-flash-image`	USD 0.50/100 万 Token	USD 3.00/100 万 Token	USD 60.00/100 万图片 Token	按图片 Token

计费时使用以下用量：

变量	Gemini 响应字段	含义
`P_TEXT`	`promptTokensDetails[modality=TEXT].tokenCount`	文本输入 Token
`P_IMAGE`	`promptTokensDetails[modality=IMAGE].tokenCount`	参考图片输入 Token
`O_TEXT`	`candidatesTokensDetails[modality=TEXT].tokenCount`	文本输出 Token
`O_IMAGE`	`candidatesTokensDetails[modality=IMAGE].tokenCount`	图片输出 Token
`THOUGHT`	`thoughtsTokenCount`	思考 Token
`N_IMAGE`	响应中返回的图片 `inlineData` 数量	实际返回图片张数

本文三个模型的文本输入和图片输入使用相同输入单价，因此可以使用
promptTokenCount 作为输入总量。candidatesTokenCount 可能同时包含文本和图片 Token，
不能将其整体按文本输出价或图片输出价计算。

输入费用 = promptTokenCount × 输入单价 ÷ 1,000,000

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

按图片 Token 计费时：
  图片输出费用 = O_IMAGE × 图片输出单价 ÷ 1,000,000

按图片张数计费时：
  图片输出费用 = N_IMAGE × 每张图片单价

请求总费用 = 输入费用 + 文本/思考输出费用 + 图片输出费用

cachedContentTokenCount 和 cacheTokensDetails 是输入 Token 的缓存子集，不能与
promptTokenCount 重复相加。如果有效价格表对缓存另行定价，应先从普通输入中扣除缓存用量，
再分别应用普通输入价和缓存价。

图片输出 Token 优先读取 candidatesTokensDetails[modality=IMAGE]。如果该明细缺失，
只有在有效价格表明确给出“模型 + 分辨率对应图片 Token”时，才可以按请求的 imageSize
回退换算；否则应以服务平台账单为准。

3. Gemini 响应字段逐项说明

3.1 响应顶层字段

字段	类型	说明
`candidates`	array	候选结果列表。每个候选可能包含文字、思考摘要和图片。
`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` 通常表示正常完成；`SAFETY`、`IMAGE_SAFETY`、`NO_IMAGE` 等表示未正常得到图片结果。
`candidates[].finishMessage`	string	对结束原因的可读补充说明，可能缺失。
`candidates[].safetyRatings`	array	当前候选的安全分类和风险概率。

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

字段	类型	说明
`content.role`	string	输出角色，通常为 `model`。
`content.parts`	array	输出片段列表，文字和图片可以同时存在。
`parts[].text`	string	模型返回的说明文字；当 `thought=true` 时表示思考摘要。
`parts[].inlineData`	object	返回的图片或其他内联媒体。
`parts[].inlineData.mimeType`	string	媒体类型，例如 `image/png` 或 `image/jpeg`。
`parts[].inlineData.data`	string	图片原始字节的 Base64，不包含 `data:image/...;base64,` 前缀。
`parts[].inlineData.displayName`	string	可选的媒体显示名称。
`parts[].thought`	boolean	是否为思考内容。普通图片结果通常不包含该字段或为 `false`。
`parts[].thoughtSignature`	string	多轮图片编辑时可能需要原样回传的不透明签名。

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，包含文本、参考图片以及可能存在的缓存输入。
`cachedContentTokenCount`	integer	缓存命中 Token，是 `promptTokenCount` 的子集，不能重复相加。
`candidatesTokenCount`	integer	候选输出总 Token，可能同时包含文本和图片 Token。
`thoughtsTokenCount`	integer	思考 Token，按文本/思考输出价格计费。
`totalTokenCount`	integer	总 Token 核验字段，不能直接乘以单一价格计算精确金额。
`promptTokensDetails`	array	输入 Token 的模态明细。图片编辑时通常同时出现 `TEXT` 和 `IMAGE`。
`cacheTokensDetails`	array	缓存 Token 的模态明细，是输入 Token 的子集。
`candidatesTokensDetails`	array	输出 Token 的模态明细。文本读取 `TEXT`，图片读取 `IMAGE`。
`serviceTier`	string	上游实际服务层级，可能缺失；最终计费仍以服务平台有效价格为准。
`*TokensDetails[].modality`	string	Token 模态，例如 `TEXT`、`IMAGE`、`AUDIO`、`VIDEO`。
`*TokensDetails[].tokenCount`	integer	对应模态的 Token 数量。

客户侧建议保存请求模型、modelVersion、responseId、完整 usageMetadata、
请求的 imageSize、实际返回图片张数、使用的价格版本和计算金额，便于后续核对。

4. 典型场景与计费示例

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

场景一：`gemini-2.5-flash-image` 文生图，按图片张数计费

示例响应：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "已根据描述生成图片。"
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<BASE64_IMAGE_DATA>"
            }
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 4000,
    "candidatesTokenCount": 1490,
    "thoughtsTokenCount": 0,
    "totalTokenCount": 5490,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 4000
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 200
      },
      {
        "modality": "IMAGE",
        "tokenCount": 1290
      }
    ]
  },
  "modelVersion": "gemini-2.5-flash-image",
  "responseId": "response-example-001"
}

字段解释：

promptTokenCount=4000：输入总量为 4,000 Token。

candidatesTokensDetails[TEXT]=200：文本输出为 200 Token。

thoughtsTokenCount=0：没有思考 Token。

响应中有 1 个图片 inlineData，所以 N_IMAGE=1。

本模型示例价格按图片张数计费，因此不要再使用 IMAGE=1290 重复计算图片费用。

输入费用 = 4,000 × USD 0.30 ÷ 1,000,000 = USD 0.00120
文本输出费用 = 200 × USD 2.50 ÷ 1,000,000 = USD 0.00050
图片输出费用 = 1 × USD 0.039 = USD 0.03900
请求总费用 = USD 0.00120 + USD 0.00050 + USD 0.03900
            = USD 0.04070

场景二：`gemini-3-pro-image` 使用参考图生成 4K 图片

示例响应：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "已完成 4K 图片编辑。"
          },
          {
            "inlineData": {
              "mimeType": "image/jpeg",
              "data": "<BASE64_IMAGE_DATA>"
            }
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 600,
    "candidatesTokenCount": 2050,
    "thoughtsTokenCount": 300,
    "totalTokenCount": 2950,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 40
      },
      {
        "modality": "IMAGE",
        "tokenCount": 560
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 50
      },
      {
        "modality": "IMAGE",
        "tokenCount": 2000
      }
    ],
    "serviceTier": "standard"
  },
  "modelVersion": "gemini-3-pro-image",
  "responseId": "response-example-002"
}

字段解释：

promptTokenCount=600：包含 40 个文本输入 Token 和 560 个参考图片输入 Token。

candidatesTokensDetails[TEXT]=50：文本输出为 50 Token。

thoughtsTokenCount=300：思考输出为 300 Token。

candidatesTokensDetails[IMAGE]=2000：4K 图片输出为 2,000 图片 Token。

candidatesTokenCount=2050 已经包含文本和图片 Token，不能再整体按某一种输出单价计算。

输入费用 = 600 × USD 2.00 ÷ 1,000,000 = USD 0.00120
文本/思考输出费用
  = (50 + 300) × USD 12.00 ÷ 1,000,000
  = USD 0.00420
图片输出费用 = 2,000 × USD 120.00 ÷ 1,000,000
             = USD 0.24000
请求总费用 = USD 0.00120 + USD 0.00420 + USD 0.24000
            = USD 0.24540

场景三：`gemini-3.1-flash-image` 生成 2K 图片，回退图片 Token

示例响应：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "图片生成完成。"
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<BASE64_IMAGE_DATA>"
            }
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 4000,
    "candidatesTokenCount": 2480,
    "thoughtsTokenCount": 200,
    "totalTokenCount": 6680,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 4000
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 800
      }
    ]
  },
  "modelVersion": "gemini-3.1-flash-image",
  "responseId": "response-example-003"
}

字段解释：

promptTokenCount=4000：输入总量为 4,000 Token。

candidatesTokensDetails[TEXT]=800：文本输出为 800 Token。

thoughtsTokenCount=200：思考输出为 200 Token。

响应缺少 candidatesTokensDetails[IMAGE]，但实际返回了 1 张 2K 图片。

有效价格表规定 2K 图片按 1,680 图片 Token 计算，因此本例使用 O_IMAGE=1680。

如果响应已经返回 IMAGE 明细，应优先使用响应值，不再按分辨率换算。

输入费用 = 4,000 × USD 0.50 ÷ 1,000,000 = USD 0.00200
文本/思考输出费用
  = (800 + 200) × USD 3.00 ÷ 1,000,000
  = USD 0.00300
图片输出费用 = 1,680 × USD 60.00 ÷ 1,000,000
             = USD 0.10080
请求总费用 = USD 0.00200 + USD 0.00300 + USD 0.10080
            = USD 0.10580

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

请求成功。响应可能包含图片、说明文字、思考摘要、用量信息或安全反馈。

Bodyapplication/json

示例

4K 图片生成成功并返回完整用量提示词被安全策略拦截

{
    "candidates": [
        {
            "content": {
                "role": "model",
                "parts": [
                    {
                        "text": "已按照要求生成图片。"
                    },
                    {
                        "inlineData": {
                            "mimeType": "image/png",
                            "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
                        }
                    }
                ]
            },
            "finishReason": "STOP",
            "index": 0,
            "safetyRatings": []
        }
    ],
    "usageMetadata": {
        "promptTokenCount": 600,
        "candidatesTokenCount": 2050,
        "thoughtsTokenCount": 300,
        "totalTokenCount": 2950,
        "promptTokensDetails": [
            {
                "modality": "TEXT",
                "tokenCount": 40
            },
            {
                "modality": "IMAGE",
                "tokenCount": 560
            }
        ],
        "candidatesTokensDetails": [
            {
                "modality": "TEXT",
                "tokenCount": 50
            },
            {
                "modality": "IMAGE",
                "tokenCount": 2000
            }
        ],
        "serviceTier": "standard"
    },
    "modelVersion": "gemini-3-pro-image",
    "responseId": "response-example-id"
}

前置阅读

1. 接口说明

2. 计费原理与计算口径

3. Gemini 响应字段逐项说明

3.1 响应顶层字段

3.2 `candidates[]` 字段

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

3.4 `promptFeedback` 和安全字段

3.5 `usageMetadata` 字段

4. 典型场景与计费示例

场景一：`gemini-2.5-flash-image` 文生图，按图片张数计费

场景二：`gemini-3-pro-image` 使用参考图生成 4K 图片

场景三：`gemini-3.1-flash-image` 生成 2K 图片，回退图片 Token

请求参数

请求示例代码

返回响应

原生Gemini格式

前置阅读#

1. 接口说明#

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

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

3.1 响应顶层字段#

3.2 candidates[] 字段#

3.3 content 和 parts[] 字段#

3.4 promptFeedback 和安全字段#

3.5 usageMetadata 字段#

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

场景一：gemini-2.5-flash-image 文生图，按图片张数计费#

场景二：gemini-3-pro-image 使用参考图生成 4K 图片#

场景三：gemini-3.1-flash-image 生成 2K 图片，回退图片 Token#

请求参数

请求示例代码

返回响应

前置阅读

1. 接口说明

2. 计费原理与计算口径

3. Gemini 响应字段逐项说明

3.1 响应顶层字段

3.2 `candidates[]` 字段

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

3.4 `promptFeedback` 和安全字段

3.5 `usageMetadata` 字段

4. 典型场景与计费示例

场景一：`gemini-2.5-flash-image` 文生图，按图片张数计费

场景二：`gemini-3-pro-image` 使用参考图生成 4K 图片

场景三：`gemini-3.1-flash-image` 生成 2K 图片，回退图片 Token