Nano Banana 图像生成与编辑

Nano Banana（香蕉生图）是 Gemini 图像系列在无界模型云上的接入，包含 Nano Banana 2（小香蕉，快）、Nano Banana Pro（大香蕉，质量优先） 与 Nano Banana 2 Lite（小香蕉 Lite，极速低价） 三款模型，支持纯文本生成图像（文生图）与参考图编辑（图生图）。

参数与能力对齐 Google 官方 Gemini 图像文档：Gemini 3.1 Flash Lite Image 与 图像生成 · 比例与尺寸。

网关同时提供两套等价协议，以 Google 原生协议为主：

• Google 原生（推荐）：POST /v1beta/models/{model}:generateContent，与 google-genai SDK / Gemini 兼容工具直接对接。
• OpenAI 兼容：POST /v1/images/generations 与 /v1/images/edits，已有 OpenAI 图像客户端零改动接入。
• 异步任务：POST /api/jobs，长耗时（4K / 多图融合）用异步提交—轮询，gpt-image-2 与 Gemini 共用同一套异步协议。

三套接口鉴权、路由、计费完全一致，网关内部统一适配底层 Gemini 契约，调用方无需关心底层协议。

鉴权与 Base

• API 数据面 Base：https://api.tos.run（浏览器控制台是 https://ai.tos.run，不要用作 API Base）
• 鉴权头：Authorization: Bearer $AI_TOS_API_KEY

API Key 在控制台创建；生产环境请把 Key 放在服务端，不要暴露到浏览器。鉴权与 Base 与 gpt-image-2 完全一致。

模型选择

三款模型共用全部接口，只是 model 字段不同。按场景选型：

Google 原生协议（generateContent）

Google Generative Language（Gemini）原生协议是本系列的首选接口。把 google-genai SDK 或任意 Gemini 兼容工具的 Base URL 指向 https://api.tos.run 即可。

• 文生图 / 改图：POST https://api.tos.run/v1beta/models/{model}:generateContent
• 模型列表：GET https://api.tos.run/v1beta/models

文生图

curl "https://api.tos.run/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "夕阳下的海边咖啡馆露台，暖色调，电影感横版构图" }] }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
    }
  }'

图片在 candidates[0].content.parts[].inlineData.data（纯 base64）：

{
  "candidates": [
    { "content": { "role": "model", "parts": [
      { "inlineData": { "mimeType": "image/png", "data": "iVBORw0KGgo..." } }
    ] } }
  ],
  "usageMetadata": { "totalTokenCount": 1290 }
}

大香蕉把 gemini-3.1-flash-image 换成 gemini-3-pro-image 即可，其它不变。小香蕉 Lite 换成 gemini-3.1-flash-lite-image，并且 imageSize 只能是 1K（传更高档位会被强制回落）。

图生图与改图

把参考图作为 inlineData 部分放进 contents[].parts，与文本一起提交。多图融合就放多个 inlineData 部分（按顺序在提示词里用「图1 / 图2」引用，最多 6 张，单张 ≤ 20MB，png/jpeg/webp）：

curl "https://api.tos.run/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [
      { "inlineData": { "mimeType": "image/png", "data": "'"$(base64 -i banana.png)"'" } },
      { "text": "在香蕉顶上加一顶小小的草编派对帽，其余保持不变" }
    ] }],
    "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": { "aspectRatio": "1:1", "imageSize": "1K" } }
  }'

尺寸与比例

Gemini 系列只支持离散比例 + 清晰度档位，不提供任意 宽x高 的像素契约。先按模型选择可用比例，再选择 1K / 2K / 4K。各模型支持的比例不同（数据对齐 Google 官方文档）：

• 比例字段为原生 imageConfig.aspectRatio，OpenAI 兼容入口使用扩展字段 aspectRatio；默认 1:1。
• 清晰度字段为原生 imageConfig.imageSize，OpenAI 兼容入口使用 size：1K / 2K / 4K。小香蕉 Lite 只出 1K——传更高档位网关会强制回落到 1K。
• 只有小香蕉支持超宽 / 超高的横竖条幅比例（1:4、4:1、1:8、8:1）；大香蕉与小香蕉 Lite 不支持这四种，传入会被上游拒绝或回落到最接近比例。

各档位在保持比例前提下的参考像素尺寸（对齐官方，实际以返回为准）：

• 上表为官方参考像素；不同调用入口与上游号源会在保持比例的前提下返回略有出入的像素，1K 横图不保证恰好 1024 像素宽。

异步任务 API（/api/jobs）

4K、多图融合等长耗时生成，建议用异步任务：一次提交拿到任务 id，再轮询结果，避免长连接在发版 / 超时时被打断。

这套异步协议对 Gemini 与 gpt-image-2 完全统一——提交 / 轮询 / 取消端点与响应结构一致，只有提交时的生成请求体不同（Gemini 用 contents，OpenAI 用 prompt）。任务状态对齐 ComfyUI 规范面的 5 态：pending → in_progress → completed | failed | cancelled（超过保留期为 expired）。

提交

POST https://api.tos.run/api/jobs。Gemini 原生体需在顶层带 model（异步端点的 URL 里没有模型段）：

# Gemini 原生形态
curl "https://api.tos.run/api/jobs" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "contents": [{ "parts": [{ "text": "赛博朋克城市夜景，4K 电影质感" }] }],
    "generationConfig": { "imageConfig": { "aspectRatio": "16:9", "imageSize": "4K" } }
  }'

# OpenAI 形态（gpt-image-2 同理，仅 model 不同）
curl "https://api.tos.run/api/jobs" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "gpt-image-2", "prompt": "赛博朋克城市夜景", "size": "4K", "aspectRatio": "16:9" }'

图生图 / 融合用 multipart/form-data（image[] 上传参考图），或在 Gemini 原生体的 contents 里放 inlineData 部分。

提交返回任务对象：

{
  "id": "b1a2c3...",
  "status": "pending",
  "model": "gemini-3-pro-image",
  "create_time": 1751540000000,
  "progress": 5,
  "progress_message": "已加入队列",
  "outputs_count": 0,
  "outputs": [],
  "execution_error": null
}

轮询

GET https://api.tos.run/api/jobs/{id}。完成后 outputs 给出可下载 URL（而非内联 base64）：

{
  "id": "b1a2c3...",
  "status": "completed",
  "progress": 100,
  "outputs_count": 1,
  "outputs": [{ "url": "https://ai.tos.run/api/files/serve/generated/xxx.png", "mime_type": "image/png" }],
  "execution_error": null
}

失败时 status:"failed"，并在顶层 execution_error 给出真实错误（含供应商侧安全拒绝等）：

{
  "id": "b1a2c3...",
  "status": "failed",
  "execution_error": { "type": "image_unsafe", "message": "content rejected by provider", "provider": "adobe-gemini" }
}

取消

POST https://api.tos.run/api/jobs/{id}/cancel，幂等：排队中的任务立即取消，运行中的任务尽力中止（若已出图则仍算完成），终态 / 未知 id 为空操作。

{ "cancelled": true }

批量取消：POST /api/jobs/cancel，体为 { "job_ids": ["id1", "id2"] }。

列表

GET https://api.tos.run/api/jobs?limit=20&offset=0 → { "jobs": [...], "pagination": { "offset": 0, "limit": 20, "has_more": false } }。

OpenAI 兼容协议（/v1/images/*）

已有 OpenAI 图像客户端可零改动接入，只需切换 Base、Key 和 model。

• 文生图：POST https://api.tos.run/v1/images/generations，application/json。
• 图生图 / 改图：POST https://api.tos.run/v1/images/edits，multipart/form-data（image / 重复 image[]），或 JSON 传 input_images（公网 URL / data URL / base64）。

curl "https://api.tos.run/v1/images/generations" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "gemini-3.1-flash-image", "prompt": "海边咖啡馆露台，电影感横版", "size": "2K", "aspectRatio": "16:9" }'

返回标准 OpenAI 形态，图片在 data[0].b64_json（纯 base64）：

{ "created": 1717488000, "data": [{ "b64_json": "/9j/4AAQSkZJRg..." }], "usage": { "generated_images": 1 } }

网关只透传它真正支持的参数（model / prompt / size / 扩展字段 aspectRatio，以及 edits 的 image / image[] / input_images），其余 OpenAI 参数会被静默忽略。同步接口没有面向调用方的流式，始终返回一次性完整 JSON。

与 gpt-image-2 的区别 / 选型建议

选型建议：

• 要快、要批量草稿 → 小香蕉 gemini-3.1-flash-image。
• 要质量、复杂构图、商业海报 → 大香蕉 gemini-3-pro-image。
• 要最低延迟 + 最低单价的高并发实时交互、轻量编辑（贴纸 / 换色 / 改背景）→ 小香蕉 Lite gemini-3.1-flash-lite-image（仅 1K）。
• 需要精确像素尺寸或 mask 局部重绘 → 优先 gpt-image-2。
• 需要超宽 / 超高条幅（1:4、4:1、1:8、8:1）→ 只有小香蕉 gemini-3.1-flash-image 支持。
• 长耗时（4K / 多图融合）→ 走异步任务 API。

价格

三款模型均按张计费，各尺寸（1K / 2K / 4K）同价；小香蕉 Lite 仅出 1K 且单价更低。具体单价、计费方式与组织专属价格，请以「价格与计费」页与控制台展示为准。