使用帮助

通过连连智枢的 /google 原生接口调用 Gemini 图片模型。

示例模型为 gemini-nano-banana-2.1-all，请替换为已在模型目录中对你开放的模型代码。鉴权使用在控制台创建的 API Key。所有 [BASE64_IMAGE_DATA] 为占位符，实际调用须替换为有效图片数据。

1. 调用入口

入口	适用场景	请求格式	返回格式
`/google/{版本}/models/{模型}:generateContent`	Google 原生调用、多轮编辑、视频输入	Google 原生 JSON	Google 原生 JSON
`/google/{版本}/models/{模型}:streamGenerateContent`	Google 原生流式调用	Google 原生 JSON	Google 原生 SSE

以上接口均使用 POST。服务地址为 https://routerbrain.ai；路径中的模型代码填写平台模型目录中的公开代码。响应为 Google 原生 JSON 或 SSE。

2. Google 原生接口

2.1 地址、鉴权与请求头

同步地址：

POST https://routerbrain.ai/google/v1beta/models/{模型代码}:generateContent

流式地址：

POST https://routerbrain.ai/google/v1beta/models/{模型代码}:streamGenerateContent?alt=sse

参数或请求头	必填	说明
路径中的版本	是	路径可使用 `v1`、`v1beta`、`v1alpha`；以所选模型支持的版本为准
路径中的模型代码	是	平台公开模型代码，例如 `gemini-nano-banana-2.1-all`
路径中的操作	是	`generateContent` 为同步；`streamGenerateContent` 为流式
`Content-Type`	是	`application/json`
`x-goog-api-key`	二选一	控制台 API Key，可与查询参数 `key` 二选一
查询参数 `key`	二选一	控制台 API Key；Google 标准别名 `$key` 也被接受。特殊字符需 URL 编码
查询参数 `alt=sse`	流式建议填写	标准 SSE 形式；是否流式由 URL 中的 `:streamGenerateContent` 决定
`x-trace-id`	否	自定义链路标识，方便关联请求
`x-user-id`	否	调用方的用户标识
`x-agent-name`	否	调用方的应用或 Agent 名称

同时提供 Header 和查询参数时，密钥必须一致。重复的 key 查询参数或相互冲突的密钥会被拒绝。此入口用 x-goog-api-key 或 key 鉴权，不能仅用 Authorization: Bearer ... 代替。

Google 对 key、$key 和 X-Goog-Api-Key 的标准定义见官方系统参数说明。

2.2 文生图：同步调用

先设置本地调用变量：

GATEWAY_URL='https://routerbrain.ai'
API_KEY='sk-REPLACE-WITH-YOUR-KEY'
MODEL_CODE='gemini-nano-banana-2.1-all'

curl --silent --show-error --fail-with-body --max-time 300 \
  "${GATEWAY_URL}/google/v1beta/models/${MODEL_CODE}:generateContent" \
  -H "x-goog-api-key: ${API_KEY}" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "生成一张橘猫坐在窗边晒太阳的图片" }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "2K"
    }
  }
}
JSON

--max-time 300 是 curl 客户端的等待上限，不是请求体参数，可以按需要调整。

若使用查询参数鉴权，保存上面的 JSON 为 request.json，然后调用：

curl --silent --show-error --fail-with-body --max-time 300 \
  "${GATEWAY_URL}/google/v1beta/models/${MODEL_CODE}:generateContent" \
  --url-query "key=${API_KEY}" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json

--url-query 适用于支持该选项的 curl，并会处理密钥的 URL 编码；前一个 Header 示例对 curl 版本的要求更低。

2.3 请求正文参数

请求体格式与 Google GenerateContent API 一致。下表列出图片生成常用字段；具体能力与取值范围因模型而异。

字段	类型	必填	说明
`contents`	`array<object>`	是	本次输入，或按时间顺序排列的对话历史
`contents[].role`	`string`	建议填写	用户输入用 `user`；历史模型回复用 `model`
`contents[].parts`	`array<object>`	是	该轮内容，可组合文本、内嵌图片、文件引用等
`parts[].text`	`string`	文本输入时	提示词、编辑要求或历史文本
`parts[].inlineData`	`object`	内嵌媒体输入时	媒体数据对象，包含 `mimeType` 和 `data`
`inlineData.mimeType`	`string`	使用内嵌媒体时	媒体 MIME，例如 `image/png`、`image/jpeg`
`inlineData.data`	`string`	使用内嵌媒体时	纯 base64 数据，不带 `data:image/...;base64,` 前缀
`parts[].fileData`	`object`	文件引用输入时	包含 `fileUri`，可携带 `mimeType`；需为模型侧可访问的地址
`fileData.fileUri`	`string`	使用文件引用时	模型侧可读取的文件 URI；可用协议与权限以 Google 文档为准
`fileData.mimeType`	`string`	建议填写	引用文件的 MIME，例如图片或 `video/mp4`
`parts[].thoughtSignature`	`string`	多轮场景按返回值保留	上一轮模型返回的签名，放回原来的 Part，不自行生成或修改
`systemInstruction`	`object`	否	系统要求，常用结构为 `{ "parts": [{ "text": "..." }] }`
`generationConfig`	`object`	图片生成建议填写	输出模态、图片规格及模型生成选项
`cachedContent`	`string`	否	已存在的缓存资源名称；本接口不会替你创建缓存
`safetySettings`	`array<object>`	否	安全配置，常用子字段为 `category`、`threshold`
`tools`	`array<object>`	否	模型工具配置；是否支持因模型而异
`toolConfig`	`object`	否	工具调用配置，与 `tools` 配合使用

单个 Part 应按 Google 定义选择其内容类型。多轮编辑时，推荐保留上一次返回的完整 content，避免丢失图片、签名或上下文。

2.4 generationConfig 参数

字段	类型	说明
`responseModalities`	`array<string>`	图片调用建议传 `["TEXT", "IMAGE"]`；只需要图片时可按模型能力传 `["IMAGE"]`
`imageConfig.aspectRatio`	`string`	输出宽高比，例如 `1:1`、`16:9`、`9:16`、`4:3`、`3:2`；具体支持集合由模型决定
`imageConfig.imageSize`	`string`	输出分辨率级别：`512`、`1K`、`2K`、`4K`；注意字母大小写，不同模型支持范围不同
`temperature`	`number`	生成采样选项；未填时使用模型默认设置
`topP`	`number`	采样选项，取值范围以 Google 文档为准
`topK`	`integer`	采样选项，部分模型不支持设置
`maxOutputTokens`	`integer`	输出 token 上限；设得过小可能截断结果，不代表输出像素或图片张数
`seed`	`integer`	模型支持时可指定随机种子，不保证不同请求结果完全一致
`candidateCount`	`integer`	候选响应数量，图片调用建议保持 `1`
`stopSequences`	`array<string>`	模型支持时设置输出停止序列
`thinkingConfig.thinkingLevel`	`string`	原生枚举包括 `MINIMAL`、`LOW`、`MEDIUM`、`HIGH`；模型可能只支持其中部分级别
`thinkingConfig.thinkingBudget`	`integer`	模型支持时设置推理预算；不要套用其他模型的范围
`thinkingConfig.includeThoughts`	`boolean`	模型支持时请求返回可用的思考内容；返回的思考图片应与最终图片区分

responseMimeType 是模型响应的 MIME 配置，不应拿它替代 inlineData.mimeType，也不应直接用它强制图片输出为 PNG/JPEG。本文图片调用使用 imageConfig；更多生成选项参考 GenerationConfig 定义。

2.5 图生图或图片编辑

请求结构如下，替换占位数据后，按 2.2 节方式发送：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "保留这只猫的外观，把背景改成海边日落" },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "[BASE64_IMAGE_DATA]"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
  }
}

文件引用形式：

{
  "fileData": {
    "mimeType": "image/jpeg",
    "fileUri": "https://example.com/reference.jpg"
  }
}

将该对象放入 contents[].parts。URL 须为模型侧可直接访问；平台不会替你下载远程图片后再转发。HTTPS、Google 文件 URI 等是否可用，以 Google 文档与模型说明为准。

需要视频输入时，在 inlineData 或 fileData 中填写相应视频 MIME；是否支持视频输入取决于具体模型。

2.6 多轮图片编辑

将上一次响应中的 candidates[0].content 完整保留为历史模型回复，然后追加新的用户要求：

{
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "生成一张窗边的橘猫图片" }]
    },
    {
      "role": "model",
      "parts": [
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "[BASE64_IMAGE_DATA]"
          },
          "thoughtSignature": "[ORIGINAL_THOUGHT_SIGNATURE]"
        }
      ]
    },
    {
      "role": "user",
      "parts": [{ "text": "猫的姿势保持不变，把窗外改为雪景" }]
    }
  ],
  "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
}

上例为结构示意；只有上一轮实际返回签名时才携带该字段。签名应与原 Part 一起保留。多轮签名规则见 Google 原生图片调用说明。

2.7 原生 SSE 调用

保存 2.2 节的请求正文为 request.json：

curl -N --silent --show-error --fail-with-body --max-time 300 \
  "${GATEWAY_URL}/google/v1beta/models/${MODEL_CODE}:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: ${API_KEY}" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json

响应为 Google 原生 SSE，每个 data: 行通常对应一个 JSON 对象。请按 SSE 事件边界解析，不要假定一次读取即完整 JSON，也不要假定一定有 [DONE] 标记。

客户端需要持续读取文本、图片和候选的最终状态。

事件结构示意（字段以实际响应为准）：

data: {"candidates":[{"index":0,"content":{"role":"model","parts":[{"inlineData":{"mimeType":"image/png","data":"[BASE64_IMAGE_DATA]"}}]}}]}

data: {"candidates":[{"index":0,"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":11,"candidatesTokenCount":1120,"totalTokenCount":1131,"promptTokensDetails":[{"modality":"TEXT","tokenCount":11}],"candidatesTokensDetails":[{"modality":"IMAGE","tokenCount":1120}]}}

SSE 以空行分隔事件；同一事件可能含多行 data:，需按 SSE 规则拼接。图片与结束状态可能在同一事件中返回。

2.8 原生返回与图片读取

响应示意：

{
  "candidates": [
    {
      "index": 0,
      "finishReason": "STOP",
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "[BASE64_IMAGE_DATA]"
            }
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 11,
    "candidatesTokenCount": 1120,
    "totalTokenCount": 1131,
    "promptTokensDetails": [{ "modality": "TEXT", "tokenCount": 11 }],
    "candidatesTokensDetails": [{ "modality": "IMAGE", "tokenCount": 1120 }]
  }
}

遍历 candidates[].content.parts[] 获取结果：

返回字段	说明
`part.text`	模型返回的文本
`part.inlineData.data`	图片的纯 base64 数据，解码后即可保存
`part.inlineData.mimeType`	实际图片 MIME，保存文件时按它选择扩展名
`part.thought`	为 `true` 时表示思考内容，应与最终图片区分
`part.thoughtSignature`	多轮请求需要保留的模型签名
`candidate.finishReason`	该候选的完成原因，应结合结果内容判断是否成功
`promptFeedback`	输入被拦截等反馈信息
`usageMetadata`	Token 用量等统计；只出现在响应中，不是请求字段

TEXT 输出可能存在而没有图片。客户端应检查图片 Part，不能仅凭 HTTP 200 判定生成了图片。

3. 错误处理与调用限制

3.1 错误格式

鉴权失败响应示例：

{
  "error": {
    "code": 401,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "UNAUTHENTICATED"
  }
}

也可能返回 Google 原生格式的错误体。请同时检查 HTTP 状态码、error、promptFeedback、各候选的 finishReason 以及是否包含图片数据。

现象	检查项
401 / `UNAUTHENTICATED`	是否传入有效 API Key，是否使用 Header `x-goog-api-key` 或查询参数 `key`
400 / `INVALID_ARGUMENT`	JSON 是否有效、密钥是否冲突或重复、模型是否支持所传选项
404 / `NOT_FOUND`	模型代码、路径版本及操作名称是否正确
403 或权限相关错误	模型是否已在控制台对你开放，Key 是否有效且账户有余额
返回文本但没有图片	是否请求了 `IMAGE`、模型是否具备图片能力、是否存在拦截或异常终态
参考图无法读取	URI 是否可被模型侧访问、MIME 是否正确；可改用 `inlineData` 内嵌 base64
图片规格报错	`imageSize` 的大小写、`aspectRatio` 格式及模型支持范围是否正确
SSE 中断或流中返回错误	按异常流处理；保留响应头 `x-request-id` 和错误信息
请求等待较久	调整客户端等待上限；`curl -N` 只关闭输出缓冲，不会加快生成

3.2 使用说明与限制

本页仅说明 generateContent 与 streamGenerateContent，不包含 Google Interactions API。
模型代码写在 URL 中，流式通过 URL 中的操作名称选择。不要用正文中的 stream: true 代替 streamGenerateContent。
模型规格通过 generationConfig.imageConfig 设置，本文不使用 OpenAI 的 size、response_format 或 n 参数。
本接口不提供文件上传或缓存创建；fileData.fileUri 与 cachedContent 须指向已存在且模型侧可引用的资源。
图片张数、视频、宽高比、分辨率与耗时会因模型而异；请求体字段能被接受，不表示模型一定支持对应能力。
仅收到 HTTP 200、部分文本或某一张图片，不足以说明 SSE 已正常完成。继续读取候选终态、反馈及错误。
图片 MIME 以实际返回值为准，不能始终把图片当作 PNG。
联系支持时请提供响应头 x-request-id、模型代码、调用的操作名与错误信息；勿提交完整 API Key 或图片 base64。

图像生成概览 · 网关错误