图片生成接口（异步任务），承载 Google Nano Banana 2.1——2026 年 10 月发布的 Nano Banana 2 升级版。文生图只需 prompt；改图把参考图放进 image 或 images（可传 URL、data: 或 base64），也可以走 /v1/images/edits。提交后立刻返回任务 id（HTTP 202），再轮询 GET /v1/images/jobs/{id} 取图。支持 1:1、3:4、2:3、9:16、4:3、3:2、16:9 等比例与 1K / 2K / 4K 分辨率，4:1、1:4、8:1、1:8 宽幅也能直接出图。按张计费，失败不计费。
在 Playground 试用 →快速开始
三步跑通：提交任务 → 查询结果 → 拿到图片链接。把 YOUR_API_KEY 换成你的 Key，下面的命令可以直接运行。
curl https://nezhagate.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "nano-banana-2.1", "prompt": "一只橘猫坐在窗台上看雨，暖色台灯，电影感，浅景深", "size": "16:9", "resolution": "2K"}'{
"id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
"object": "image.generation.job",
"status": "queued",
"created": 1791281500,
"model": "nano-banana-2.1"
}curl https://nezhagate.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \ -H "Authorization: Bearer YOUR_API_KEY"
{
"id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
"object": "image.generation.job",
"status": "succeeded",
"created": 1791281500,
"model": "nano-banana-2.1",
"data": [
{"url": "https://img.nezhagate.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
],
"usage": {"images": 1, "resolution": "2K", "model": "nano-banana-2.1"}
}第 3 步 · data[0].url 就是图片链接（PNG），保留 60 天；需要长期使用，请下载到你自己的存储。
import time
import requests
BASE = "https://nezhagate.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
# 1. 提交任务
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
"model": "nano-banana-2.1",
"prompt": "一只橘猫坐在窗台上看雨，暖色台灯，电影感，浅景深",
"size": "16:9",
"resolution": "2K",
}).json()
if "error" in job:
raise SystemExit(job["error"]["message"])
# 2. 每 3 秒查询一次，直到结束
while job["status"] not in ("succeeded", "failed"):
time.sleep(3)
job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()
# 3. 下载图片
if job["status"] == "succeeded":
url = job["data"][0]["url"]
with open("nano-banana-2.1.png", "wb") as f:
f.write(requests.get(url).content)
print("saved", url)
else:
print("failed:", job["error"]["message"])认证
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
在控制台创建 API Key 后即可调用。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型 ID，此处为 nano-banana-2.1。 |
| prompt | string | 是 | 图片描述提示词。 |
| size | string | 否 | 输出比例。推荐直接传宽高比：1:1、3:4、2:3、9:16、4:3、3:2、16:9，模型按该比例原生出图，主体不会被裁切；也兼容像素尺寸（如 1024x1024、1024x1536、1536x1024）。默认 1:1（方图）。 |
| resolution | string | 否 | 分辨率档位：1K（默认）/ 2K / 4K，按档位计费。配合 size 里的比例使用，例如 {"size": "16:9", "resolution": "2K"}；每档的实际像素见下方「比例、分辨率与输出尺寸」。size 直接写像素时（如 2048x1152），按长边判断档位。 |
| n | integer | 否 | 固定为 1：每个任务只出 1 张。传更大的值也只出 1 张、只收 1 张的钱；需要多张请同时提交多个任务。 |
| image | string | 否 | 图生图模式：参考图，可传公网 URL、data: URI 或 base64。提供后即走真正的图生图（保留原图人物/主体），在其基础上按所选 size 比例重绘；等价于调用 /v1/images/edits。 |
| images | array | 否 | 多张参考图，最多 8 张（超过 8 张时只用前 8 张）：字符串数组，或 [{"image_url": "..."}] 对象数组；每张可以是公网图片直链、data: URI 或 base64，单张不超过 16MB。传了即走图生图，等价于 /v1/images/edits。只有 1 张时也可以用上面的 image 字段。 |
请求示例
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-2.1", "prompt": "a serene ink-wash poster, lots of negative space", "size": "16:9", "resolution": "2K"}'
# 2) poll until status=succeeded
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'响应示例
{
"id": "img_3f9a...c2",
"object": "image.generation.job",
"status": "queued",
"model": "nano-banana-2.1"
}价格
按张计费，价格只看分辨率档位，与比例、文生图还是图生图无关。提交时按档位预扣，任务失败会自动全额退回。1 积分 = $0.005。
| 档位 | 积分 / 张 | 美元 / 张 |
|---|---|---|
| 1K | 3 | $0.015 |
| 2K | 5 | $0.025 |
| 4K | 8 | $0.04 |
每个任务固定出 1 张：n 传多少都只出 1 张、只收 1 张的钱。需要多张请同时提交多个任务（同一账号最多 50 张同时生成）。
比例、分辨率与输出尺寸
size 填比例，resolution 填档位（1K 默认、2K、4K）。模型按所选比例直接出图，不是先出方图再裁切。交付图片的长边是 1024 / 2048 / 4096 像素，另一边按比例换算。常用比例：
| 比例 | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 3:4 | 768x1024 | 1536x2048 | 3072x4096 |
| 2:3 | 683x1024 | 1365x2048 | 2731x4096 |
| 9:16 | 576x1024 | 1152x2048 | 2304x4096 |
| 4:3 | 1024x768 | 2048x1536 | 4096x3072 |
| 3:2 | 1024x683 | 2048x1365 | 4096x2731 |
| 16:9 | 1024x576 | 2048x1152 | 4096x2304 |
除上表 7 种外，4:5、5:4、21:9、1:4、4:1、1:8、8:1 也按比例原生出图（长边规则相同）。其他比例会先按最接近的横版、竖版或方形出图，再裁成你要的比例，可能裁掉部分画面。
size 也可以直接写像素（如 1536x1024），按所写尺寸交付，档位按长边判断：不超过 1536 为 1K，不超过 2048 为 2K，更大为 4K。resolution 只认 1K / 2K / 4K（大小写均可），其他值会被忽略，档位改按 size 判断，默认 1K。不传 size 时出 1:1 方图。
图生图与参考图
- 传 image（1 张）或 images（多张，最多 8 张；超过 8 张时只用前 8 张）即走图生图，在提示词里写清楚要怎么改。也可以调用 POST /v1/images/edits，参数相同。
- 每张参考图可以是公网图片直链（http / https）、data: URI 或纯 base64，单张不超过 16MB，JPEG、PNG、WebP 等常见格式都可以。
- 链接必须能直接下载到图片本身，不能是网页、需要登录或有防盗链的地址。读不到的参考图会在提交时直接返回 400 并写明原因，不建任务、不扣费。
- 输出比例由 size 决定，不跟随参考图；想保持原图比例，请把 size 设成和原图一致。
- 参考图由我们代为托管，只保留 7 天。
curl https://nezhagate.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "nano-banana-2.1", "prompt": "保留人物，把背景换成夜晚的海边，加上暖色灯串", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'任务状态与返回字段
GET /v1/images/jobs/{id} 的返回始终带 id、object（image.generation.job）、status、created（Unix 秒）和 model，其余字段随状态出现：
| status | 含义 | 这时多出的字段 |
|---|---|---|
| queued | 排队中 | queue_position（前面还有几个任务）、eta_seconds（预计等待秒数，仅供参考） |
| processing | 生成中 | — |
| succeeded | 已完成 | data[].url（图片链接，本站图床保留 60 天）；usage.images（交付张数）、usage.resolution（计费档位） |
| failed | 失败，预扣的费用已全额退回 | error.message、error.type、error.code |
建议每 2～3 秒查一次。同一账号最多 50 张同时生成，更多的任务按提交顺序排队；排队超过 15 分钟仍未开始的任务会自动失败并全额退款。任务记录保留 3 天，之后用任务号查询会返回 404，但图片链接在 60 天内仍然有效。任务号只能由提交它的账号查询。
出图时间
从提交到拿到结果的常见用时，仅供参考。图生图比文生图多几秒到十几秒；个别任务在自动换线重试时会到 1～2 分钟。
| 档位 | 常见用时 |
|---|---|
| 1K | 25–40 秒 |
| 2K | 25–50 秒 |
| 4K | 35–80 秒 |
错误与退款
所有错误都是同一个结构：{"error": {"message", "type", "code", "param"}}，请按 code 判断。
提交时直接返回的错误（不建任务，也不扣费）
| HTTP | code | 原因 | 怎么办 |
|---|---|---|---|
| 400 | missing_prompt | prompt 为空 | 补上 prompt |
| 400 | model_not_found | model 写错，或这个型号当前不可用 | 检查型号名，可用型号见 /v1/models |
| 400 | invalid_request | 参考图读不到（链接打不开、不是图片、超过 16MB 等），message 写明是哪一张、什么原因 | 换成能直接下载的图片链接，或改传 base64 |
| 401 | invalid_api_key | Key 错误、已删除或已停用 | 到控制台检查 Key |
| 402 | insufficient_quota | 余额不够预扣这一单 | 充值后重试 |
| 429 | rate_limit_exceeded | 超过了这个 Key 自己设置的每分钟请求上限 | 降低频率，或在控制台调高这个 Key 的上限 |
| 503 | model_maintenance | 模型维护中 | 稍后重试，维护信息见状态页 |
| 503 | service_unavailable | 我们这边临时出错（如参考图托管失败） | 稍后重试 |
任务失败（提交成功后 status 变成 failed，预扣的费用全额退回）
| 情况 | 你会看到 | 怎么办 |
|---|---|---|
| 提示词或参考图没通过 Google 的安全审核 | error.message 为 Content blocked 等审核提示 | 改写提示词或换参考图；原样重新提交通常还会被拦 |
| 生成线路临时故障或超时（我们会先自动换到其他线路重试，全部失败才返回失败） | error.code 为 upstream_error、upstream_timeout 等，message 说明原因 | 直接重新提交即可 |
| 排队超过 15 分钟仍未开始 | error.message 说明排队超时 | 稍后重新提交 |
用 Webhook 代替轮询
生产环境建议用 Webhook：提交时加上 callback_url，任务结束（成功或失败）时，我们会把和查询接口完全相同的 JSON POST 到这个地址，事件为 image.completed / image.failed，并带签名头供你验证来源。也可以在「设置 → Webhook」里给整个账号配置一个地址。 Webhook 文档
curl https://nezhagate.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "nano-banana-2.1", "prompt": "一只橘猫坐在窗台上看雨，暖色台灯，电影感，浅景深", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'