功能与支持模型

原生流式使用与同步调用相同的 contents 和 generationConfig。示例采用稳定版 gemini-3.1-flash-image、16:9、1K；Pro 可使用相同配置，Lite 使用 1K 与常用比例。

流式可以较早收到内容，但不是图片生成百分比，也不承诺持续传来低清预览。一个网络 chunk 可能只有半行 JSON，或包含多个 SSE 事件；不能对每个 chunk 直接 JSON.parse，也不能把 SSE 文本保存成 PNG。

第一步：设置鉴权

使用请求头 Authorization: Bearer YOUR_API_KEY。将 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的空格；基础地址为 https://top.qingyuntop.ai。

第二步：调用模型

POST https://top.qingyuntop.ai/v1beta/models/gemini-3.1-flash-image:streamGenerateContent?alt=sse

请求 Content-Type 为 application/json；正常响应 Content-Type 为 text/event-stream。流式动作写在路径中；请求体不填 stream:true。

请求参数

字段与类型位置、填写规则与限制
contents；object[]必填；JSON 顶层数组，至少一轮。单轮传 user；多轮依次传完整历史和新的 user 内容。
generationConfig.responseModalities；string[]可选；推荐 ["TEXT", "IMAGE"]；只需图片可用 ["IMAGE"]。不要仅填 TEXT。省略时由模型决定输出模态；并不保证一定产生图片。
generationConfig.imageConfig.aspectRatio；string可选；字符串。省略时参考输入比例，否则通常为 1:1。通用 10 种与 Flash 扩展 4 种见模型表；不填写像素宽高。
generationConfig.imageConfig.imageSize；string可选；3.x 默认 1K。Pro：1K/2K/4K；Flash：512/1K/2K/4K；Lite 使用 1K；2.5 省略。512 是字符串，不带 px 或 K；K 必须大写。

可切换代码示例

点击横向标签切换语言。cURL 使用 Bash，需支持 --fail-with-body；文件/历史示例还需 jq 和 base64。Python 需安装 requests；Node.js 需 20 或更新版本，保存为 .mjs。示例的 600 秒超时是客户端设置，不是生成时限承诺。建议每个示例使用独立目录；同名输出文件会覆盖。

set -euo pipefail
cat > request-template.json <<'JSON'
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "生成一张水彩风格的海边灯塔插画，蓝白配色，柔和的晨光，画面中不要出现文字。"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "TEXT",
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "1K"
    }
  }
}
JSON
cp request-template.json request.json
[ "$(wc -c < request.json)" -lt 20000000 ] || { echo "请求超过 20 MB，请压缩图片或缩短历史" >&2; exit 1; }
curl --fail-with-body --connect-timeout 30 --max-time 600 --no-buffer "https://top.qingyuntop.ai/v1beta/models/gemini-3.1-flash-image:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output stream.sse

SSE 事件与完成判断

每个事件以空行结束，将同一事件里的多行 data: 用换行连接后解析为 JSON。忽略 : 开头的注释等无数据行。原生事件的主体是 generateContent 响应结构，主要读取 candidates[].content.parts[]；不是 choices[].delta，也不是 image_generation.completed。

普通文字在 part.text，图片在 part.inlineData。跳过 thought=true 的临时内容；对每个完整图片块按 MIME 解码保存。finishReason=STOP 表示该候选正常结束；还应确认实际收到非思考图片。usageMetadata 可能在后续事件出现，不能把各事件重复携带的累计值直接相加。

原生流不以 OpenAI [DONE] 作为必须存在的完成标记。示例容忍此标记，但依赖图片数据、候选终止信息和流的结束来判断结果；若收到错误对象或安全终止原因，会报错。

保存、断线与限制

cURL 保存原始 stream.sse；Python/Node.js 保存解码图片与 stream-events.json 事件数组。stream-events.json 不是同步 response.json，不能直接用于多轮示例。需要继续编辑时，优先使用同步多轮流程。

超时、断线或停止读取不等于上游取消。本入口没有按 responseId 查询进度、恢复流或取消任务的工作流；请记录请求时间、模型及收到的响应标识，联系本站支持确认，避免断线后立即重复生成。已经保存的图片与最终请求是否成功是两个独立判断。

常见错误与参考

收到 JSON 而非 SSE 时先检查 HTTP 状态与错误正文；不要把错误当图片。响应有文字但没有图片时按错误排查处理。官方参考：streamGenerateContent、图片生成。