Gemini generateContent API-文本多模态生成-AutoRouter

通过 /v1beta/models/{model}:generateContent 调用 Gemini 模型生成内容。支持多轮对话、多模态输入、JSON 模式、函数调用、安全设置与流式输出。

通过模型生成一次响应。可以传入纯文本，也可以传入图像、音频、视频和文档；支持多轮历史、系统指令、工具调用、JSON 输出、安全设置与上下文缓存。

当前为 Beta 接口，路径在 /v1beta/ 下。不同模型、包括微调模型支持的输入能力各不相同，具体以平台模型广场为准。

本文档包含两个方法：

generateContent：传入 GenerateContentRequest，一次返回完整的 GenerateContentResponse
streamGenerateContent：以流式返回 GenerateContentResponse，请求体同样使用 GenerateContentRequest

与 Interactions API 的区别：本接口使用 contents / parts 的原生 Gemini 结构，生成参数放在 generationConfig，模型名写在路径里；Interactions API 使用 input / steps 结构，模型名写在请求体里。

Base URL

https://api.autorouter.top — Production

Authentication

BearerAuth: http (bearer) 使用 Bearer Token 认证。格式: Authorization: Bearer sk-xxxxxx

Endpoints

POST `/v1beta/models/{model}:generateContent`

生成内容

给定一个 GenerateContentRequest，生成模型响应。

Path Parameters

Name	Type	Required	Description
`model`	string	Yes	用于生成内容的模型名称。格式 `models/{model}`，路径中写作 `models/gemini-3.8-flash:generateContent`

Headers

Name	Type	Required	Description
`Authorization`	string	Yes	请求身份认证。格式：`Bearer sk-xxxxxx`
`Content-Type`	string	Yes	固定为 `application/json`

Request Body

Content-Type: application/json

Example:

{
  "contents": [
    {
      "parts": [
        { "text": "写一个关于魔法背包的故事。" }
      ]
    }
  ]
}

GenerateContentRequest 字段说明：

请求体就是一个 GenerateContentRequest。下表列出它的顶层字段及本页直接展开的常用嵌套字段；Content & Part、Tool 与其他复杂对象的详细结构见表格后的对应章节。

Name	Type	Required	Description
`contents`	Content[]	Yes	当前对话内容。单轮请求传一个元素；多轮请求传完整历史加最新一条
`contents[].role`	string	No	内容的发送方：`user` / `model`。单轮请求可省略
`contents[].parts`	Part[]	Yes	构成一条消息的内容块
`systemInstruction`	Content	No	开发者设定的系统指令。目前仅支持文本
`tools`	Tool[]	No	模型可调用的工具声明列表
`toolConfig`	object	No	对 `tools` 的配置
`toolConfig.functionCallingConfig`	object	No	函数调用配置
`toolConfig.functionCallingConfig.mode`	string	No	函数调用模式：`AUTO` / `ANY` / `NONE` / `VALIDATED`。未指定时为 `AUTO`
`toolConfig.functionCallingConfig.allowedFunctionNames`	string[]	No	限制模型可调用的函数名。仅在 `mode` 为 `ANY` 或 `VALIDATED` 时设置
`toolConfig.retrievalConfig`	object	No	检索配置
`toolConfig.retrievalConfig.latLng`	object	No	用户所在位置，含 `latitude` 与 `longitude`
`toolConfig.retrievalConfig.languageCode`	string	No	用户语言，使用 BCP47 语言标签
`toolConfig.includeServerSideToolInvocations`	boolean	No	为 `true` 时，响应的 Content 中会带上服务端工具的调用与结果
`safetySettings`	object[]	No	拦截不安全内容的设置列表。每个类别最多一条
`safetySettings[].category`	string	Yes	有害内容类别。安全设置存在时必填
`safetySettings[].threshold`	string	Yes	拦截阈值。安全设置存在时必填
`generationConfig`	object	No	模型生成与输出的配置
`generationConfig.stopSequences`	string[]	No	遇到这些字符序列时停止输出，最多 5 个。停止序列本身不包含在响应中
`generationConfig.responseMimeType`	string	No	输出的 MIME 类型：`text/plain`（默认）、`application/json`、`text/x.enum`
`generationConfig.responseFormat`	object	No	响应输出格式配置，按模态（文本、音频、图像）分别指定。官方推荐用它取代 `responseSchema` 与 `_responseJsonSchema`
`generationConfig.responseSchema`	object	No	已弃用，请改用 `responseFormat`。约束 JSON 输出结构的 Schema（OpenAPI 子集）。需同时设置 `responseMimeType`
`generationConfig.responseJsonSchema`	object	No	以 JSON Schema 约束输出结构。与 `responseSchema` 互斥，需同时设置 `responseMimeType`
`generationConfig.responseModalities`	string[]	No	响应的模态，须与模型支持的某种模态组合完全一致，否则报错。空列表等同于仅文本
`generationConfig.candidateCount`	integer	No	返回的候选响应数量。未设置时为 1。Gemini 1.0 系列不支持
`generationConfig.maxOutputTokens`	integer	No	候选响应中最多包含的 token 数。默认值因模型而异
`generationConfig.temperature`	number	No	采样温度，范围 [0.0, 2.0]。Gemini 3.6 Flash 及更新的模型会忽略该字段
`generationConfig.topP`	number	No	核采样阈值。Gemini 3.6 Flash 及更新的模型会忽略该字段
`generationConfig.topK`	integer	No	每步仅在概率最高的 K 个 token 中采样。Gemini 3.6 Flash 及更新的模型会忽略该字段
`generationConfig.seed`	integer	No	解码使用的随机种子。未设置时随机生成
`generationConfig.presencePenalty`	number	No	存在惩罚。token 已出现过即施加（开关式，与出现次数无关）。正值降低重复、增加词汇多样性
`generationConfig.frequencyPenalty`	number	No	频率惩罚。按 token 已出现的次数累加。负值过大会让模型反复输出同一 token，直至触达 `maxOutputTokens`
`generationConfig.responseLogprobs`	boolean	No	为 `true` 时在响应中返回 logprobs
`generationConfig.logprobs`	integer	No	每步返回的 top logprobs 数量（含已选中的候选），范围 [0, 20]。仅当 `responseLogprobs` 为 `true` 时有效
`generationConfig.enableEnhancedCivicAnswers`	boolean	No	启用增强的公民类问题回答。并非所有模型可用
`generationConfig.speechConfig`	object	No	语音生成配置
`generationConfig.thinkingConfig`	object	No	思考功能配置。模型不支持思考时设置该字段会报错
`generationConfig.imageConfig`	object	No	图像生成配置。模型不支持时设置该字段会报错
`generationConfig.mediaResolution`	string	No	输入媒体的分辨率
`generationConfig.enableAffectiveDialog`	boolean	No	启用后模型会识别情绪并相应调整回复
`generationConfig.translationConfig`	object	No	翻译配置
`generationConfig.audioTranscriptionConfig`	object	No	音频转写（语音识别）配置
`cachedContent`	string	No	作为上下文使用的已缓存内容名称。格式 `cachedContents/{cachedContent}`
`serviceTier`	string	No	请求的服务层级：`unspecified`（默认，等同 `standard`）、`standard`、`flex`、`priority`
`store`	boolean	No	配置本次请求的日志行为。设置后优先于项目级日志配置
`labels`	object	No	自定义标签。键和值长度均不超过 63 个字符，只能包含小写字母、数字、下划线和短横线。键必须以字母开头
`continuationToken`	string	No	用于续接上一次以 `CONTINUATION` 结束的生成。Base64 字符串

modelstring（路径参数，必选）

用于生成内容的模型名称，写在路径里：/v1beta/models/{model}:generateContent。

具体模型 ID 以 AutoRouter 平台模型广场及 API Key 可见模型为准。

contentsobject[]（必选）

当前对话的内容。

单轮：传一个 Content
多轮：传历史消息加最新一条，role 在 user 与 model 之间交替

每个 Content 由 role 和 parts 组成。parts 里可以放文本、内联的 Base64 媒体、已上传文件的引用、函数调用与函数结果等，详见 Content & Part。

systemInstructionobject（可选）

开发者设定的系统指令，结构同 Content。目前仅支持文本。

{
  "systemInstruction": {
    "parts": [{ "text": "你是一只名叫 Neko 的猫。" }]
  }
}

toolsobject[]（可选）

模型在本次请求中可以调用的工具。Tool 是一段能让系统与外部系统交互的代码，用来执行模型自身知识和能力之外的操作。

官方接口说明里明确支持的是函数（functionDeclarations）与代码执行（codeExecution）。响应里还会出现 Google 搜索、URL 上下文、文件检索、Google 地图等工具产生的元数据，详见 Tool。

toolConfigobject（可选）

对 tools 的配置。

safetySettingsobject[]（可选）

拦截不安全内容的设置列表。设置同时作用于 contents 和返回的 candidates，不满足阈值的内容与响应会被拦截。

每个 category 最多一条设置
列表中指定的类别会覆盖该类别的默认设置；未指定的类别使用默认设置

示例：

{
  "safetySettings": [
    { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE" },
    { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH" }
  ]
}

generationConfigobject（可选）

模型生成与输出的配置。

示例：

{
  "generationConfig": {
    "stopSequences": ["Title"],
    "temperature": 1.0,
    "maxOutputTokens": 800,
    "topP": 0.8,
    "topK": 10
  }
}

temperature、topP、topK 在 Gemini 3.6 Flash 及更新的模型上会被静默忽略，示例仅用于展示字段写法。

responseMimeType / responseSchemastring / objectJSON 模式

JSON 模式让模型输出符合给定 Schema 的 JSON，便于直接解析。

在 generationConfig 中设置 responseMimeType 为 application/json
在 generationConfig.responseSchema 中给出结构，类型名使用大写：STRING、NUMBER、INTEGER、BOOLEAN、OBJECT、ARRAY；或在 generationConfig.responseJsonSchema 中用标准 JSON Schema（小写类型名）。两者互斥
响应的 candidates[0].content.parts[0].text 就是一段 JSON 字符串，需要自行 JSON.parse

官方已将 responseSchema 标记为弃用，推荐改用 generationConfig.responseFormat。responseFormat 的子字段结构（ResponseFormatConfig）尚待官方核对，下方示例仍使用 responseSchema，该字段目前仍可使用。

{
  "contents": [{ "parts": [{ "text": "列出 5 种常见的饼干配方" }] }],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "ARRAY",
      "items": {
        "type": "OBJECT",
        "properties": {
          "recipe_name": { "type": "STRING" },
          "ingredients": { "type": "ARRAY", "items": { "type": "STRING" } }
        },
        "required": ["recipe_name"]
      }
    }
  }
}

responseJsonSchema 支持的 JSON Schema 子集（官方 GenerationConfig 说明，仅以下属性受支持）：

类别	可用字段
标识与引用	`$id`、`$defs`、`$ref`、`$anchor`
通用	`type`（`string` / `number` / `integer` / `boolean` / `object` / `array` / `null`）、`format`、`title`、`description`
`object`	`properties`、`required`、`additionalProperties`（布尔值或 Schema）
`string` / `number`	`enum`（适用于字符串与数字）
`number` / `integer`	`minimum`、`maximum`
`array`	`items`、`prefixItems`、`minItems`、`maxItems`
组合	`anyOf`、`oneOf`（按 `anyOf` 处理）
非标准	`propertyOrdering`（可选，指定属性输出顺序）

另有：允许为空时写作 {"type": ["string", "null"]}（官方 JSON Schema 指南）。

使用限制：

循环引用只会被有限展开，因此只能用在非必填属性里（可为空的属性不算非必填）
子 Schema 上设置了 $ref 后，除以 $ 开头的属性外，不能再设置其他属性

注意事项：

输出保证是语法合法的 JSON，但字段值是否合理仍需在应用里校验
过大或嵌套过深的 Schema 可能被拒绝
不支持完整的 JSON Schema 规范，仅支持上述子集
JSON 模式适合「格式化最终回答」；需要模型在回答前请求你执行动作时，使用函数调用

cachedContentstring（可选）

作为上下文使用的已缓存内容。格式 cachedContents/{cachedContent}。缓存内容只能搭配创建它时所用的模型使用。

设置后，usageMetadata.promptTokenCount 仍是有效提示词的总大小，其中包含缓存内容的 token；缓存部分的 token 数见 cachedContentTokenCount。

serviceTierstring（可选）

请求的服务层级。实际生效的层级会在响应的 usageMetadata.serviceTier 中返回。

值	说明
`unspecified`	默认服务层级，即标准层级
`standard`	标准服务层级
`flex`	Flex 服务层级
`priority`	优先服务层级

各层级在 AutoRouter 上是否放行及计费方式，以平台实际配置为准。

storeboolean（可选）

配置本次请求的日志行为。设置后，优先于项目级的日志配置。

labelsobject（可选）

附加在请求上的自定义元数据，键值均为字符串。

键必须以字母开头
键和值长度均不超过 63 个字符（Unicode 码点），只能包含小写字母、数字、下划线和短横线，允许国际字符
聚合方可用键 safety_identifier 传递安全标识，例如 {"safety_identifier": "user_session_123"}

continuationTokenstring（可选）

用于续接上一次以 finishReason: "CONTINUATION" 结束的生成。

来源：上一次 generateContent 或 streamGenerateContent 响应中 candidates[].continuationToken
使用时，contents 必须与首次请求的提示词和对话历史完全一致
Base64 编码字符串

Responses

200: 请求成功，返回 GenerateContentResponse

Content-Type: application/json

400: 请求参数错误

Content-Type: application/json

401: 鉴权失败

402: 余额不足

403: API Key 无权访问该模型

429: 请求频率限制

请求示例

curl -X POST "https://api.autorouter.top/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "contents": [
    {
      "parts": [
        { "text": "写一个关于魔法背包的故事。" }
      ]
    }
  ]
}'

把历史放进 contents，role 用 user 表示用户，model 表示模型上一轮回复。

curl -X POST "https://api.autorouter.top/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "contents": [
    { "role": "user", "parts": [{ "text": "你好" }] },
    { "role": "model", "parts": [{ "text": "你好，需要我帮你做什么？" }] },
    { "role": "user", "parts": [{ "text": "我家里有两只狗，一共有几只爪子？" }] }
  ]
}'

parts 里同时放文本和图像。小图用 Base64 的 inlineData，大文件见「文件引用」。

curl -X POST "https://api.autorouter.top/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "contents": [
    {
      "parts": [
        { "text": "这张图片里有什么？" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "BASE64_ENCODED_IMAGE"
          }
        }
      ]
    }
  ]
}'

官方示例使用的是下划线写法 inline_data / mime_type，两种写法均为 Gemini REST 接口所接受。

音频、视频、PDF 等较大的文件先通过 Files API 上传，再用 fileData 引用其 fileUri。

curl -X POST "https://api.autorouter.top/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "contents": [
    {
      "parts": [
        { "text": "请总结这份文档。" },
        {
          "fileData": {
            "mimeType": "application/pdf",
            "fileUri": "FILE_URI_FROM_FILES_API"
          }
        }
      ]
    }
  ]
}'

视频文件上传后需要等待处理完成（文件状态变为 ACTIVE）再发起生成。Files API 在 AutoRouter 上是否可用，请以平台文档为准。

用 responseMimeType 加 responseSchema 约束输出。

curl -X POST "https://api.autorouter.top/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "contents": [
    { "parts": [{ "text": "列出 5 种常见的饼干配方" }] }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "ARRAY",
      "items": {
        "type": "OBJECT",
        "properties": {
          "recipe_name": { "type": "STRING" },
          "ingredients": { "type": "ARRAY", "items": { "type": "STRING" } }
        },
        "required": ["recipe_name"]
      }
    }
  }
}'

先声明函数。模型决定调用时，候选的 content.parts 里会出现 functionCall。执行函数后，把结果以 functionResponse 放进下一轮 contents 发回。

curl -X POST "https://api.autorouter.top/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "systemInstruction": {
    "parts": [{ "text": "你是一个灯光控制机器人，只能开关灯和设置颜色。" }]
  },
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "enable_lights",
          "description": "打开灯光系统。"
        },
        {
          "name": "set_light_color",
          "description": "设置灯光颜色。灯光必须已打开才能生效。",
          "parameters": {
            "type": "object",
            "properties": {
              "rgb_hex": {
                "type": "string",
                "description": "6 位十六进制颜色，例如 ff0000 表示红色。"
              }
            },
            "required": ["rgb_hex"]
          }
        },
        {
          "name": "stop_lights",
          "description": "关闭灯光系统。"
        }
      ]
    }
  ],
  "toolConfig": {
    "functionCallingConfig": { "mode": "AUTO" }
  },
  "contents": [
    { "role": "user", "parts": [{ "text": "请把灯打开。" }] }
  ]
}'

回传函数结果的下一轮请求（contents 部分）：

{
  "contents": [
    { "role": "user", "parts": [{ "text": "请把灯打开。" }] },
    { "role": "model", "parts": [{ "functionCall": { "name": "enable_lights", "args": {} } }] },
    {
      "role": "user",
      "parts": [
        { "functionResponse": { "name": "enable_lights", "response": { "result": "ok" } } }
      ]
    }
  ]
}

toolConfig.functionCallingConfig.mode 设为 ANY 可强制模型返回函数调用，并可用 allowedFunctionNames 限定可选函数。

curl -X POST "https://api.autorouter.top/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "systemInstruction": {
    "parts": [{ "text": "你是一只猫，名字叫 Neko。" }]
  },
  "contents": [
    { "parts": [{ "text": "早上好！你好吗？" }] }
  ]
}'

curl -X POST "https://api.autorouter.top/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "contents": [
    { "parts": [{ "text": "解释一下 AI 是如何工作的" }] }
  ],
  "generationConfig": {
    "stopSequences": ["Title"],
    "temperature": 1.0,
    "maxOutputTokens": 800,
    "topP": 0.8,
    "topK": 10
  }
}'

curl -X POST "https://api.autorouter.top/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "safetySettings": [
    { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH" },
    { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE" }
  ],
  "contents": [
    { "parts": [{ "text": "写一句关于对手球队的讽刺短句。" }] }
  ]
}'

被拦截的提示词会在响应的 promptFeedback.blockReason 中给出原因，被拦截的候选会在 finishReason 中给出原因，两种情况下都应读取 safetyRatings 排查。

先通过缓存接口创建缓存，再在请求里用 cachedContent 引用。

curl -X POST "https://api.autorouter.top/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "contents": [
    { "role": "user", "parts": [{ "text": "请总结这份转录稿" }] }
  ],
  "cachedContent": "cachedContents/abc123"
}'

缓存内容只能搭配创建它时所用的模型使用。缓存创建接口在 AutoRouter 上是否可用，请以平台文档为准。

响应示例

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "从前，有一个旧书包，每当主人背上它，就能听见森林里的风声……"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 312,
    "totalTokenCount": 321,
    "promptTokensDetails": [
      { "modality": "TEXT", "tokenCount": 9 }
    ]
  },
  "modelVersion": "gemini-3.8-flash",
  "responseId": "RESPONSE_ID"
}

示例中的文本、ID 与 token 数仅作示意。

safetyRatings[].probability 的取值（HarmProbability）表示内容不安全的可能性，不代表危害的严重程度：

值	说明
`HARM_PROBABILITY_UNSPECIFIED`	未指定
`NEGLIGIBLE`	内容不安全的可能性可忽略
`LOW`	内容不安全的可能性低
`MEDIUM`	内容不安全的可能性中等
`HIGH`	内容不安全的可能性高

safetyRatings 的其他字段（如 category、blocked）待官方核对。

GenerateContentResponse 字段说明：

成功响应就是一个 GenerateContentResponse。下表列出它的顶层字段，以及常用的 candidates 和 promptFeedback 嵌套字段；finishReason、usageMetadata 等复杂字段的详细说明紧随表格之后。

Name	Type	Description
`candidates`	object[]	模型返回的候选响应。仅当提示词本身有问题时才会完全不返回候选（见 `promptFeedback`）
`candidates[].content`	Content	模型生成的内容。仅输出
`candidates[].finishReason`	string	模型停止生成的原因，见下方说明。为空表示尚未停止
`candidates[].finishMessage`	string	停止原因的详细说明。仅在设置了 `finishReason` 时出现
`candidates[].safetyRatings`	object[]	候选的安全评级，每个类别至多一条
`candidates[].citationMetadata`	object	引用信息。可能包含从训练数据中「复述」的受版权保护的段落
`candidates[].tokenCount`	integer	该候选的 token 数
`candidates[].index`	integer	候选在候选列表中的序号
`candidates[].avgLogprobs`	number	候选的平均对数概率
`candidates[].logprobsResult`	object	响应 token 及候选 token 的对数似然
`candidates[].groundingMetadata`	object	启用 grounding 时返回的元数据，见下方说明
`candidates[].groundingAttributions`	object[]	对有依据回答作出贡献的来源归因。主要用于 `GenerateAnswer` 调用
`candidates[].urlContextMetadata`	object	URL 上下文工具的检索元数据
`candidates[].continuationToken`	string	`finishReason` 为 `CONTINUATION` 时返回，用于续写。Base64 字符串
`promptFeedback`	object	提示词在内容过滤方面的反馈
`promptFeedback.blockReason`	string	提示词被拦截的原因。设置后不会返回任何候选，需改写提示词
`promptFeedback.safetyRatings`	object[]	提示词的安全评级，每个类别至多一条
`usageMetadata`	object	token 用量
`modelVersion`	string	生成响应所用的模型版本。仅输出
`responseId`	string	响应的标识。仅输出
`modelStatus`	object	模型当前状态。仅输出

finishReasonstring

模型停止生成 token 的原因：

值	说明
`FINISH_REASON_UNSPECIFIED`	默认值，未使用
`STOP`	到达自然停止点，或命中提供的停止序列
`MAX_TOKENS`	达到请求中指定的最大 token 数
`SAFETY`	候选内容因安全原因被标记
`RECITATION`	候选内容因复述原因被标记
`LANGUAGE`	候选内容使用了不受支持的语言
`OTHER`	未知原因
`BLOCKLIST`	内容含有禁用词，生成停止
`PROHIBITED_CONTENT`	内容可能包含禁止内容，生成停止
`SPII`	内容可能包含敏感个人身份信息（SPII），生成停止
`MALFORMED_FUNCTION_CALL`	模型生成的函数调用无效
`IMAGE_SAFETY`	生成的图像含有安全违规，生成停止
`IMAGE_PROHIBITED_CONTENT`	生成的图像含有其他禁止内容，图像生成停止
`IMAGE_OTHER`	因其他杂项问题，图像生成停止
`NO_IMAGE`	模型应生成图像但没有生成
`IMAGE_RECITATION`	因复述原因，图像生成停止
`UNEXPECTED_TOOL_CALL`	模型生成了工具调用，但请求中没有启用任何工具
`TOO_MANY_TOOL_CALLS`	模型连续调用工具次数过多，系统退出执行
`MISSING_THOUGHT_SIGNATURE`	请求中至少缺少一个思考签名
`MALFORMED_RESPONSE`	因响应格式错误而结束
`ESCALATION`	请求被升级规则过滤
`PUP_LIMITED_DISABLED`	因违反禁止使用政策（PUP），账号被限制或停用，生成停止
`CONTINUATION`	响应达到单次请求的 token 上限但生成尚未完成。可用返回的 `continuationToken` 续写。`maxOutputTokens` 在续写中累计，必须单调增大或省略

promptFeedback.blockReasonstring

提示词被拦截的原因：

值	说明
`BLOCK_REASON_UNSPECIFIED`	默认值，未使用
`SAFETY`	因安全原因被拦截。查看 `safetyRatings` 了解是哪个类别
`OTHER`	因未知原因被拦截
`BLOCKLIST`	因含有术语黑名单中的词被拦截
`PROHIBITED_CONTENT`	因含有禁止内容被拦截
`IMAGE_SAFETY`	候选因生成了不安全的图像内容被拦截

usageMetadataobject

本次请求的 token 用量，可作为用量核对依据。

modelStatusobject

底层模型的状态，用于提示模型所处阶段以及下线时间。

modelStage：模型阶段，取值见下表
retirementTime：模型下线时间，RFC 3339 格式，例如 2014-10-02T15:01:23Z
message：说明模型状态的文字

`modelStage`	说明
`MODEL_STAGE_UNSPECIFIED`	未指定
`UNSTABLE_EXPERIMENTAL`	底层模型频繁调整。已弃用
`EXPERIMENTAL`	仅供实验
`PREVIEW`	比实验阶段更成熟
`STABLE`	稳定，可用于生产
`LEGACY`	即将弃用，仅现有客户可用
`DEPRECATED`	已弃用，不可使用。该枚举值本身已弃用
`RETIRED`	已下线，不可使用

groundingMetadataobject

启用 grounding（搜索、地图、文件检索等）时，候选上返回的元数据。

POST `/v1beta/models/{model}:streamGenerateContent`

流式生成内容

以流的形式返回模型响应。请求体同样使用 GenerateContentRequest。需要用服务端事件（SSE）接收时，在查询参数里加 alt=sse。

Path Parameters

Name	Type	Required	Description
`model`	string	Yes	用于生成内容的模型名称，格式 `models/{model}`

Query Parameters

Name	Type	Required	Description
`alt`	string	No	设为 `sse` 时，以 Server-Sent Events 返回；每条事件的 `data` 是一个完整的 `GenerateContentResponse`

Request Body

使用 GenerateContentRequest，字段与 generateContent 相同。

Responses

200: 请求成功，返回一连串 GenerateContentResponse

请求示例

curl -N -X POST "https://api.autorouter.top/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "contents": [
    { "parts": [{ "text": "写一个关于魔法背包的故事。" }] }
  ]
}'

响应示例

alt=sse 时，每条事件的 data 是一个 GenerateContentResponse，文本按到达顺序拼接得到完整回复；finishReason 与完整的 usageMetadata 出现在最后一个分块里。

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"从前，"}]},"index":0}],"modelVersion":"gemini-3.8-flash","responseId":"RESPONSE_ID"}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"有一个旧书包，"}]},"index":0}],"modelVersion":"gemini-3.8-flash","responseId":"RESPONSE_ID"}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"每当主人背上它……"}]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":9,"candidatesTokenCount":312,"totalTokenCount":321},"modelVersion":"gemini-3.8-flash","responseId":"RESPONSE_ID"}

流式响应的注意点：

每个分块的结构与非流式响应相同，同样要检查 promptFeedback 与 finishReason
groundingMetadata.groundingChunks 在流式时只包含此前分块中尚未出现的片段
函数调用同样以 functionCall Part 出现在分块里
结构化输出（JSON 模式）流式返回的分块是合法的 JSON 片段，拼接后才是完整对象

Content & Part

contents[].parts 与候选的 content.parts 使用内容块（Part）。一个 Part 在数据联合字段（data）中至多填一种内容；填写 inlineData 原始字节时，必须带有固定的 IANA MIME 类型。

数据字段（互斥，至多设置一个）：

字段	类型	说明
`text`	string	内联文本
`inlineData`	object (Blob)	内联的媒体字节，含 `mimeType`、`data`（Base64）
`fileData`	object (FileData)	基于 URI 的数据，含 `mimeType`、`fileUri`
`functionCall`	object (FunctionCall)	模型预测的函数调用，包含 `FunctionDeclaration.name` 以及参数和取值
`functionResponse`	object (FunctionResponse)	函数调用的执行结果，包含函数名和一个结构化 JSON 对象，作为后续轮次的上下文
`executableCode`	object (ExecutableCode)	模型生成、用于执行的代码
`codeExecutionResult`	object (CodeExecutionResult)	`ExecutableCode` 的执行结果
`toolCall`	object (ToolCall)	服务端工具调用。模型预测出应在服务端执行的工具调用时填充，客户端需要把该消息原样回传
`toolResponse`	object (ToolResponse)	服务端 `ToolCall` 的执行输出，由客户端填入对应的执行结果

元数据字段（互斥，用于控制额外预处理）：

字段	类型	说明
`videoMetadata`	object (VideoMetadata)	视频元数据，仅当视频数据放在 `inlineData` 或 `fileData` 中时指定

其他可选字段：

字段	类型	说明
`thought`	boolean	该内容块是否为模型的思考内容
`thoughtSignature`	string	思考内容的不透明签名，Base64 编码，可在后续请求中回传复用
`partMetadata`	object (Struct)	附加在内容块上的自定义元数据，例如内容来源的文件名，或用于多路复用多个内容块流
`mediaResolution`	object (MediaResolution)	该输入媒体的分辨率
`mediaProcessing`	string (MediaProcessing)	模型理解该内容块媒体的处理方式。仅对视频有意义（`inlineData` 或 `fileData` 为视频类型），其他类型忽略
`audioTranscription`	object (AudioTranscription)	音频（输入或输出）的转写，仅当内容块包含音频数据时设置
`speechMetadata`	object (SpeechMetadata)	作用于文本内容块，用于定制朗读或合成方式，例如指定说话人或说话风格

Blob、FileData、FunctionCall、FunctionResponse、ExecutableCode、CodeExecutionResult、ToolCall、ToolResponse、VideoMetadata 等嵌套类型的内部字段，除下方示例中出现的以外，待官方核对。

常见的 mimeType：

类型	示例
图像	`image/png`、`image/jpeg`、`image/webp`、`image/heic`、`image/heif`
音频	`audio/wav`、`audio/mp3`、`audio/aiff`、`audio/aac`、`audio/ogg`、`audio/flac`
视频	`video/mp4`、`video/mpeg`、`video/mov`、`video/avi`、`video/webm`
文档	`application/pdf`、`text/plain`、`text/csv`

各模型实际支持的类型与大小限制不同，以平台模型广场为准。

{
  "text": "Hello, how are you?"
}

Tool

tools 声明模型可以调用的工具。是否调用、调用哪一个，由 toolConfig.functionCallingConfig.mode 控制：AUTO、ANY、NONE、VALIDATED。

Tool 是让系统与外部系统交互、执行模型自身知识和能力范围之外的动作的一段代码。每个 Tool 对象中可设置下列字段：

字段	类型	说明
`functionDeclarations[]`	object[] (FunctionDeclaration)	可供模型调用的函数声明列表。模型或系统不会执行函数，而是把函数以 `FunctionCall` 连同参数返回给客户端执行；下一轮请求可带上 `FunctionResponse`（Content 的 `role` 为 `function`）作为生成上下文。模型可能只调用其中一部分函数
`googleSearchRetrieval`	object (GoogleSearchRetrieval)	由 Google 搜索支持的检索工具
`codeExecution`	object (CodeExecution)	让模型在生成过程中执行代码
`googleSearch`	object (GoogleSearch)	Google 搜索工具，由 Google 提供支持，响应带 `groundingMetadata`
`computerUse`	object (ComputerUse)	让模型直接与计算机交互。启用后会自动填充 computer-use 专用的函数声明
`urlContext`	object (UrlContext)	网址上下文检索工具，响应带 `urlContextMetadata`
`fileSearch`	object (FileSearch)	文件检索工具，从语义检索语料库中检索知识
`mcpServers[]`	object[] (McpServer)	要连接的 MCP 服务器
`googleMaps`	object (GoogleMaps)	用地理空间上下文为回答提供依据，响应带 `maps` 类型的 grounding 片段

各工具类型的内部字段（除 functionDeclarations 的 name、description、parameters 以外）待官方核对。模型是否支持某个工具，以及 AutoRouter 是否放行，以平台实际配置为准。

FunctionDeclaration 的 parameters 是描述函数参数的 Schema，写法同 JSON 模式里的 responseSchema：

{
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "查询指定地点的当前天气",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "城市，例如 上海"
              }
            },
            "required": ["location"]
          }
        }
      ]
    }
  ]
}

模型决定调用函数时，响应候选的 content.parts 里会出现 functionCall。执行完函数后，把结果作为 functionResponse 追加到 contents 再发回。

上下文缓存

反复使用同一份大文件或长提示词时，可以先创建缓存，再在生成请求里通过 cachedContent 引用，降低成本与延迟。

缓存内容只能搭配创建它时所用的模型使用
缓存的 ttl 或 expireTime 可以更新，其余字段创建后不可变
创建缓存时可带 contents、tools、systemInstruction、toolConfig，这些字段创建后不可变

缓存相关接口在官方文档的 Caching 章节，在 AutoRouter 上是否开放以平台文档为准。

错误处理

HTTP 400 参数错误

场景	处理建议
`contents` 为空或结构错误	检查 `contents[].parts`，每条消息至少一个 Part
多轮历史的 `role` 不合法	`role` 只能是 `user` 或 `model`，并按对话顺序交替
`responseSchema` 与 `responseMimeType` 不匹配	使用 JSON 模式时，同时设置 `responseMimeType: "application/json"`
Schema 过大或嵌套过深	简化 Schema 后重试
`safetySettings` 同一类别出现多次	每个 `category` 只保留一条
续写时 `contents` 与首次请求不一致	续写必须完整复现首次请求的提示词和历史
未知模型名	使用平台模型广场中对该 API Key 开放的模型 ID

HTTP 401 / 403 鉴权错误

401 Unauthorized：API Key 无效或已过期
403 Forbidden：API Key 无权访问此模型（检查 token 的模型白名单）

现象	处理建议
没有 `candidates`，有 `promptFeedback.blockReason`	提示词被拦截。查看 `promptFeedback.safetyRatings`，改写提示词或调整 `safetySettings`
`finishReason` 为 `SAFETY` / `PROHIBITED_CONTENT` / `BLOCKLIST` / `SPII`	候选被过滤。查看 `safetyRatings`，调整提示词
`finishReason` 为 `RECITATION`	内容因复述被标记，改写请求
`finishReason` 为 `MAX_TOKENS`	输出被截断，提高 `generationConfig.maxOutputTokens` 后重试
`finishReason` 为 `CONTINUATION`	响应未完成。携带 `continuationToken` 续写，并单调增大或省略 `maxOutputTokens`
`finishReason` 为 `MALFORMED_FUNCTION_CALL`	函数调用无效。检查函数声明与参数 Schema，或改用 `VALIDATED` 模式
`finishReason` 为 `UNEXPECTED_TOOL_CALL`	模型返回了工具调用，但请求没有启用工具。检查 `tools` 与 `toolConfig`
`finishReason` 为 `TOO_MANY_TOOL_CALLS`	模型连续调用工具过多。收紧工具描述或限制可调用的函数
`finishReason` 为 `MISSING_THOUGHT_SIGNATURE`	多轮历史中缺少思考签名。回传历史时保留模型返回的完整 Part
`finishReason` 为 `NO_IMAGE` / `IMAGE_*`	图像生成未成功。调整提示词后重试
`finishReason` 为 `PUP_LIMITED_DISABLED`	账号因违反禁止使用政策被限制或停用
JSON 模式下 `text` 不是合法 JSON	检查是否因 `MAX_TOKENS` 被截断；校验 Schema 是否过于复杂
读取 `parts[0].text` 报错	先判断 `candidates` 是否存在、`parts` 里是否是 `functionCall` 等非文本 Part

文本聊天

modelstring（路径参数，必选）

可选模型（示例）

contentsobject[]（必选）

systemInstructionobject（可选）

toolsobject[]（可选）

toolConfigobject（可选）

属性

safetySettingsobject[]（可选）

属性

generationConfigobject（可选）

属性

responseMimeType / responseSchemastring / objectJSON 模式

cachedContentstring（可选）

serviceTierstring（可选）

storeboolean（可选）

labelsobject（可选）

continuationTokenstring（可选）

finishReasonstring

promptFeedback.blockReasonstring

usageMetadataobject

属性

modelStatusobject

groundingMetadataobject

属性

目录