POST/v1/gemini/models/{model}:streamGenerateContent

Gemini 多模态流式生成

用于 Gemini 协议流式生成。请求体与 generateContent 基本一致，contents.parts 同样支持 text、inlineData 和 fileData 图片输入，响应为 SSE 分片；鉴权、模型权限、余额、用量、日志与计费均复用平台 Responses 链路。

基础信息

鉴权	Authorization: Bearer sk-... / x-goog-api-key: sk-... / ?key=sk-...
请求类型	application/json
响应类型	text/event-stream

请求参数

Path

字段

类型

必填

位置

说明

model

string

是

path

平台模型 ID，写在 Gemini 路径中。

示例："gemini-2.5-flash"

Body

字段

类型

必填

位置

说明

contents

array<object>

是

body

Gemini 内容数组。parts 支持 text、inlineData 和 fileData，可用于图文问答、OCR、图片理解等图片输入场景。

role

string

否

body

内容角色。

示例："user"

parts

array<object>

是

body

内容片段。

systemInstruction

object

否

body

系统指令；官方文档当前说明为 text only。

role

string

否

body

内容角色。

示例："user"

parts

array<object>

是

body

内容片段。

tools

array<object>

否

body

工具列表。

functionDeclarations

array<object>

否

body

函数声明列表。

googleSearchRetrieval

object

否

body

Google Search 检索工具。

codeExecution

object

否

body

代码执行工具。

googleSearch

object

否

body

Google Search 工具。

computerUse

object

否

body

Computer Use 工具。

urlContext

object

否

body

URL 上下文工具。

toolConfig

object

否

body

工具配置。

functionCallingConfig

object

否

body

函数调用策略。

retrievalConfig

object

否

body

检索策略。

safetySettings

array<object>

否

body

安全设置。

category

string

是

body

安全分类。

示例："HARM_CATEGORY_HATE_SPEECH"

threshold

string

是

body

安全阈值。

示例："BLOCK_ONLY_HIGH"

generationConfig

object

否

body

生成配置。

candidateCount

integer

否

body

候选数。

示例：1

stopSequences

array<string>

否

body

停止序列。

示例：["</end>"]

maxOutputTokens

integer

否

body

最大输出 token 数。

示例：512

temperature

number

否

body

温度。

示例：0.7

topP

number

否

body

Top-p。

示例：0.95

topK

integer

否

body

Top-k。

示例：40

seed

integer

否

body

随机种子。

示例：42

responseMimeType

string

否

body

候选输出 MIME 类型。

示例："application/json"

responseSchema

object

否

body

候选输出 Schema。

responseJsonSchema

object

否

body

候选输出 JSON Schema。

responseModalities

array<string>

否

body

响应模态。

示例：["TEXT"]

presencePenalty

number

否

body

出现惩罚。

示例：0

frequencyPenalty

number

否

body

频率惩罚。

示例：0

responseLogprobs

boolean

否

body

是否返回 logprobs。

示例：false

logprobs

integer

否

body

每步返回的 top logprobs 数量。

示例：5

enableEnhancedCivicAnswers

boolean

否

body

是否启用增强 civic 回答。

示例：false

speechConfig

object

否

body

语音生成配置。

thinkingConfig

object

否

body

思考配置。

imageConfig

object

否

body

图像生成配置。

mediaResolution

string

否

body

媒体分辨率。

示例："HIGH"

cachedContent

string

否

body

缓存内容名称。

示例："cachedContents/abc123"

serviceTier

string

否

body

服务层级。

示例："standard"

store

boolean

否

body

是否记录请求日志。

示例：false

请求示例

json

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请流式输出这张图片的识别结果。"
        },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAIAAABMXPacAAABXUlEQVR42u3dwQnCQBBA0VRhAbZhLzaRDuzNdjyJ4MkcBJG4kihmZiQv/Armkcu6E7vT+abEOiMAAEAAAAgAAAEAIAAABACAAAAQAAACAEAAAAgAAJUB8DQfAAAAAAAAAAAAAAAAAAAA4G+e7XEPIHTccwKQM/evJQD8fvQfMVQB2B0ukcVMf44BgGWnP2kAYNnRTzIACJr+OwMAAGoABEy/aQAgdPqvBgCipz8yAAAgFSBl+s8GAAAAWC1A4vQfBgAAAAAAAAAAAMEA6dO/5w3wBgAAAAAAAAAAnIY6DQUAAIDfhAEAcC/IzTg349wNBQDAfoANGRsydsRsSa5gS9KeMACb8r4VAcDXUgAAAAAAAAAAAACMn2u/qRwAAAAAAAAAAAAAAAAAAAAAwFmQsyAAAAAAqAAgf2cLQAAACAAAAQAgAAAEAIAAABAAAAIAQAAACAAAAQAgAADUagAbMOXIAHaxNAAAAABJRU5ErkJggg=="
          }
        }
      ]
    }
  ]
}

响应示例

json

{
  "responseId": "resp-123",
  "modelVersion": "gemini-2.5-flash",
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "千云模型网关"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [],
      "citationMetadata": {},
      "tokenCount": 8,
      "groundingMetadata": {},
      "index": 0
    }
  ],
  "promptFeedback": {
    "blockReason": null,
    "safetyRatings": []
  },
  "usageMetadata": {
    "promptTokenCount": 8,
    "cachedContentTokenCount": 0,
    "candidatesTokenCount": 8,
    "toolUsePromptTokenCount": 0,
    "thoughtsTokenCount": 0,
    "totalTokenCount": 16,
    "promptTokensDetails": [],
    "cacheTokensDetails": [],
    "candidatesTokensDetails": [],
    "toolUsePromptTokensDetails": []
  }
}

响应字段

字段

类型

必填

位置

说明

responseId

string

否

body

响应 ID。

示例："resp-123"

modelVersion

string

否

body

用于生成响应的模型版本。

示例："gemini-2.5-flash"

promptFeedback

object

否

body

提示过滤反馈。

blockReason

string

否

body

提示被屏蔽原因。

示例："SAFETY"

safetyRatings

array<object>

否

body

提示安全评分。

candidates

array<object>

否

body

候选响应。

content

object

否

body

模型生成内容。

finishReason

string

否

body

停止原因。

示例："STOP"

safetyRatings

array<object>

否

body

候选安全评分。

citationMetadata

object

否

body

引用元数据。

tokenCount

integer

否

body

候选 token 数。

示例：28

groundingAttributions

array<object>

否

body

检索归因信息。

groundingMetadata

object

否

body

检索 grounding 元数据。

avgLogprobs

number

否

body

平均 log 概率。

示例：-0.4

logprobsResult

object

否

body

logprobs 结果。

urlContextMetadata

object

否

body

URL 上下文元数据。

index

integer

否

body

候选索引。

示例：0

finishMessage

string

否

body

停止原因详情。

usageMetadata

object

否

body

token 使用统计。

promptTokenCount

integer

否

body

提示 token 数。

示例：12

cachedContentTokenCount

integer

否

body

缓存内容 token 数。

示例：0

candidatesTokenCount

integer

否

body

候选 token 总数。

示例：28

toolUsePromptTokenCount

integer

否

body

工具使用 prompt token 数。

示例：0

thoughtsTokenCount

integer

否

body

思考 token 数。

示例：0

totalTokenCount

integer

否

body

总 token 数。

示例：40

promptTokensDetails

array<object>

否

body

提示输入的模态统计。

cacheTokensDetails

array<object>

否

body

缓存输入的模态统计。

candidatesTokensDetails

array<object>

否

body

响应输出的模态统计。

toolUsePromptTokensDetails

array<object>

否

body

工具使用 prompt 的模态统计。

错误码

HTTP	code	说明
400	`invalid_request_error`	请求体结构不合法、缺少必填参数，或 JSON 无法解析。
401	`invalid_auth_header`	缺少或传错鉴权头，网关无法识别当前调用身份。
403	`model_not_allowed`	当前 API Key 没有访问该模型的权限。
402	`insufficient_balance`	余额不足，平台在调用前预检时已拒绝请求。
503	`model_not_available`	当前模型没有可用路由或上游渠道不可用。

在线调试

Playground · 浏览器直连网关