Nano Banana（Gemini 图像模型）

通用信息

• Base URL：https://api.routeapi.ai
• 认证：Authorization: Bearer $ROUTEAPI_KEY，使用 sk- 开头的 API Key（在控制台 API Keys 页面创建）。rat_ 开头的管理密钥不能调用模型。
• 错误格式：{"error": {"message": "...", "type": "...", "code": "..."}}，状态码含义见常见错误。

当前在售的 Gemini 图像模型：gemini-3.1-flash-image-preview、gemini-3-pro-image-preview 和 gemini-3.1-flash-lite-image。它们是由 Gemini 渠道提供的图像生成模型，有两条调用路径（每个模型的实际列表请在模型中查看 supported_endpoint_types）：

路径	端点	你发送的请求体
OpenAI 图像格式	POST /v1/images/generations	OpenAI 图像 JSON，格式见 OpenAI 图像格式
Gemini 原生	POST /v1beta/models/{model}:generateContent	Gemini 的 contents + generationConfig

客户端已经使用 Gemini 协议（Google GenAI SDK）、需要完整控制 responseModalities 和 imageConfig 时，走原生路径；客户端只支持 OpenAI 图像接口时，走 /v1/images/generations。

通过 /v1/images/generations 调用

请求格式、认证和错误响应体与 OpenAI 图像格式 相同。RouteAPI 会把你的图像请求转换成 Gemini 的 generateContent 调用。

请求参数

字段	类型	必填	说明
model	string	是	Gemini 图像模型 ID，如 gemini-3.1-flash-image-preview
prompt	string	是	作为 user 轮次里的单个文本 part 发送
size	string	否	映射为 generationConfig.imageConfig.aspectRatio（见下表）
n	integer	否	大于 1 时发送为 generationConfig.candidateCount；为 1 或省略时不发送
quality、response_format、style、user、watermark	—	否	该路径不做转换，Gemini 适配器会忽略这些字段

responseModalities 由 RouteAPI 自己填入 ["TEXT", "IMAGE"]，通过这个端点时不需要传。安全设置取自平台级的 Gemini 配置。

尺寸到宽高比

只有以下精确的 size 值会映射为宽高比：

size	aspectRatio
256x256、512x512、1024x1024	1:1
1536x1024	3:2
1024x1536	2:3
1024x1792	9:16
1792x1024	16:9

已经包含 : 的值会作为宽高比原样传递。其他值（例如 2K 或 auto）完全不发送 imageConfig，由上游默认值决定。该路径不接受像素尺寸——宽高比是唯一的尺寸控制项。

请求示例

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "A nano banana wearing sunglasses, studio product shot",
    "size": "1536x1024"
  }'

响应

响应会被转换成 OpenAI 图像对象；只有内联图像 part 会保留，模型返回的任何文本都会被丢弃。

{
  "created": 1740000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

该路径不会产生 URL——始终读取 data[].b64_json。响应里没有图像 part 时请求以 500 失败；被 Gemini 拦截时以 400 失败，拦截原因会记录在该请求上。

Caution

不要用 /v1/images/edits 给 Gemini 图像模型传参考图。它走的是文本对话路径：只转换 prompt，image / images / mask 会被忽略，返回的是内容中带 Markdown 图片的 OpenAI 对话补全，而不是图像对象。需要图像输入时请使用下面的原生请求。

使用 generateContent 原生调用

POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent?alt=sse

示例：

curl https://api.routeapi.ai/v1beta/models/gemini-3-pro-image-preview:generateContent \
  -H "x-goog-api-key: $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "role": "user", "parts": [{ "text": "Draw a cat astronaut on the moon" }] }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
    }
  }'

Gemini 认证

在 /v1beta 路径上，API Key 可以用三种方式之一传递：x-goog-api-key: $ROUTEAPI_KEY、查询参数 ?key=$ROUTEAPI_KEY，或 Authorization: Bearer $ROUTEAPI_KEY。同时存在多个时，?key= 和 x-goog-api-key 会覆盖 Authorization。

请求字段

字段	类型	必填	说明
contents	array	是	Gemini 对话内容，至少一项。角色为 user 和 model
generationConfig.responseModalities	array of string	实际必填	必须包含 IMAGE，否则模型只返回文本
generationConfig.imageConfig	object	否	图像选项，原样传给 Gemini。aspectRatio 如 1:1、3:2、16:9；imageSize 如 1K、2K、4K。可接受的值取决于模型
generationConfig.candidateCount	integer	否	候选数量；并非所有图像模型都支持
safetySettings	array	否	Gemini 安全设置，原样转发
systemInstruction	object	否	系统指令；也接受 snake_case 的 system_instruction

generationConfig 的字段同时接受 camelCase 和 snake_case 两种写法（例如 responseModalities / response_modalities、imageConfig / image_config），两者都存在时以 snake_case 为准。imageConfig 及其内容不做校验，原样传递，因此不支持的 imageSize 由 Gemini 报错，而不是 RouteAPI。

Note

原生请求不会像 OpenAI 路径那样被改写：RouteAPI 不会替你补 responseModalities。漏掉它是最常见的「请求成功返回文本、没有图像」的原因。

图像输入

要编辑或引用图像，在文本旁加一个内联图像 part：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Repaint this photo as a watercolor illustration" },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA..."
          }
        }
      ]
    }
  ],
  "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
}

inlineData 携带 Base64 图像字节，会原样转发给 Gemini。已经上传到 Google 的文件也可以用原生 fileData.fileUri part，它同样属于转发范围。如果客户端使用的是 OpenAI 对话格式，image_url 内容 part 会在服务端下载并转换成内联 part 后再发给 Gemini。

流式输出

流式由查询参数 ?alt=sse 决定，而不是由 action 名决定：带上它后上游 action 变为 streamGenerateContent，响应是 Gemini 的 server-sent events 流。每个分块都是标准的 candidates[].content.parts 结构。希望图像增量到达时使用；否则 :generateContent 会一次返回完整响应体。

响应

原生路径原样返回 Gemini 的响应结构：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "Here is the image." },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 1120,
    "totalTokenCount": 1132
  }
}

图像从 parts[].inlineData 读取，通常会伴随文本 part。Gemini 拦截请求时，promptFeedback.blockReason 会有值，candidates 为空。

计费

Gemini 图像模型按 token 计费：生成的图像计为输出 token，按输出价格收费；prompt 和参考图计为输入 token。当前费率见模型定价与模型详情页。

接下来

• OpenAI 图像格式 — 共用的 /v1/images 请求格式与编辑行为。
• Seedream — 火山引擎 Seedream 的尺寸与编辑语义。
• 模型 — 查找图像模型并确认 image-generation 支持。
• 模型定价 — 按 token 与按张计费。