Nano Banana
- 文生图与多图参考
- 一次最多 4 张，参考图最多 20MB
- 官方版按 token 计费，扩展版按张计费
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求结构
请求体是平铺的 JSON，创作字段与输出字段都在顶层，没有 content 数组包装。
The body is flat JSON: creative fields and output fields sit at the top level, with no content array wrapper.
支持的场景
| 场景 | 字段组合 |
|---|---|
| 文生图 | prompt |
| 单图编辑 | prompt + image（1 张） |
| 多图参考 | prompt + image（多张） |
不带 image 是文生图，带任意 image 进入图生图或编辑。size 省略或为 auto 时，编辑模式输出比例跟随参考图。
| Scenario | Field combination |
|---|---|
| Text to image | prompt |
| Single-image edit | prompt + image (1 image) |
| Multi-image reference | prompt + image (several images) |
Without image it's text to image; any image switches to image to image or editing. When size is omitted or auto, edit-mode output follows the reference image's ratio.
请求参数
提交成功只返回任务 ID，不含图片本身。拿结果用 task_id 轮询获取任务状态，图片地址在 result.images[0].url，该地址会过期，请及时转存。
取值 gemini-nano-banana-2.1 或 gemini-nano-banana-2.1-ext。
两者画质与尺寸完全一致，差别在计费方式与出图张数。
画面描述，中英文均可。
宽高比，默认 auto。
取值 1:4、4:1、1:8、8:1、1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9，也接受 16x9 写法。
取值 1K（默认）、2K、4K，兼容小写。
0.5K 与 512 返回 400；3K 这类无法识别的值会按 1K 出图并计费。
生成张数，默认 1。
官方版取值 1 到 4；扩展版只能为 1，传 2 到 4 会在执行阶段失败并全额退款。
参考图，公网地址或 Base64 Data URI。建议用 PNG、JPEG、WEBP。
单张不超过 20MB，扩展版合计不超过 50MB。
仅扩展版使用，扩展失败时回落到官方模型，默认 false。
任务完成回调地址。
A successful submission returns only the task ID, not the image itself. Poll Get task status with the task_id; the image URL is at result.images[0].url and expires, so copy it promptly.
gemini-nano-banana-2.1 or gemini-nano-banana-2.1-ext.
Both have identical quality and dimensions; they differ in billing method and image count per call.
The scene description, in Chinese or English.
Aspect ratio, default auto.
Values: 1:4, 4:1, 1:8, 8:1, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9; the 16x9 spelling is also accepted.
1K (default), 2K, or 4K; lowercase accepted.
0.5K and 512 return a 400; unrecognized values such as 3K render at 1K and bill as 1K.
Number of images, default 1.
The official model accepts 1 to 4; the extended model accepts only 1, and passing 2 to 4 fails during execution with a full refund.
Reference images, public URLs or Base64 Data URIs. PNG, JPEG, and WEBP are recommended.
At most 20MB each, and at most 50MB in total for the extended model.
Used by the extended model only: falls back to the official model if the extension fails. Defaults to false.
The callback URL for task completion.
输出尺寸参考
| 比例 | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024×1024 | 2048×2048 | 4096×4096 |
| 16:9 | 1376×768 | 2752×1536 | 5504×3072 |
| 21:9 | 1584×672 | 3168×1344 | 6336×2688 |
表格中混有实测值与推算值，以返回文件为准。
| Ratio | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024×1024 | 2048×2048 | 4096×4096 |
| 16:9 | 1376×768 | 2752×1536 | 5504×3072 |
| 21:9 | 1584×672 | 3168×1344 | 6336×2688 |
The table mixes measured and extrapolated values; the returned file takes precedence.
响应
提交成功返回受理结构：
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}状态码，200 表示任务已受理。
本次提交的任务列表。
受理状态，提交成功时为 submitted。
任务 ID，用它轮询结果。
完成态返回：
{
"code": 200,
"data": {
"id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
"status": "completed",
"progress": 100,
"result": {
"images": [
{ "url": ["https://cdn.oairoute.com/f/image/task_01K8_0.png"], "expires_at": 1763174708 }
]
},
"created": 1763088289,
"completed": 1763088302
}
}A successful submission returns an accepted structure:
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}The status code; 200 means the task was accepted.
The list of tasks submitted this time.
The acceptance status; submitted on success.
The task ID; use it to poll for the result.
The completed state returns:
{
"code": 200,
"data": {
"id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
"status": "completed",
"progress": 100,
"result": {
"images": [
{ "url": ["https://cdn.oairoute.com/f/image/task_01K8_0.png"], "expires_at": 1763174708 }
]
},
"created": 1763088289,
"completed": 1763088302
}
}错误码
| HTTP | 含义 |
|---|---|
| 400 | 参数错误，type 为 invalid_request_error |
| 401 | Token 缺失或无效，type 为 authentication_error |
| 402 | 余额不足，type 为 payment_required |
| 429 | 触发限流 |
| HTTP | Meaning |
|---|---|
| 400 | Invalid parameters, with type invalid_request_error |
| 401 | Token missing or invalid, with type authentication_error |
| 402 | Insufficient balance, with type payment_required |
| 429 | Rate limit hit |
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
支持的模型列表
| 模型 ID | 定位 |
|---|---|
gemini-nano-banana-2.1 | 官方版，按实际 token 计费，一次可出 1 到 4 张 |
gemini-nano-banana-2.1-ext | 扩展版，按分辨率固定单价，一次只能出 1 张 |
需要批量出图选官方版；需要成本可预测选扩展版。
这两个模型不是 Gemini 3.1 Flash Image 的别名，模型名不能互换；从那边迁移过来要去掉 0.5K。
GET https://api.oairoute.com/api/pricing。| Model ID | Positioning |
|---|---|
gemini-nano-banana-2.1 | Official model, billed by actual tokens, 1 to 4 images per call |
gemini-nano-banana-2.1-ext | Extended model, flat per-resolution pricing, 1 image per call |
Choose the official model for batch output; choose the extended model for predictable cost.
These two models aren't aliases for Gemini 3.1 Flash Image, and the model names aren't interchangeable; migrating from there means dropping 0.5K.
GET https://api.oairoute.com/api/pricing.