Nano Banana 2.1
用提示词生成 1–4 张图片，可以带参考图，最高 4k，按张计费。
Nano Banana 2.1（产品 nano_banana）用提示词生成图片，可以带最多 14 张参考图。最高 4k，生成时可以联网搜索网页和图片。一个任务出 1–4 张，按张计费。
创建任务
https://api.nanoapi.ai/v1/tasks用所有模型共用的创建任务接口，model 传 "nano-banana-2.1"。接口通常不到 1 秒返回，几秒内按 num_outputs 张冻结费用；任务结束后获取结果。
请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <API Key>，见鉴权 |
Content-Type | 是 | application/json |
Idempotency-Key | 否 | 每个新任务一个唯一字符串，建议用 UUID（1–255 个字符），见防止重复创建 |
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | nano-banana-2.1 |
prompt | string | 是 | 描述要生成的图片，最长 8000 字符。引用参考图写 @Image1、@Image2…，见在提示词里引用图片 |
image_urls | string[] | 否 | 参考图，最多 14 张；不传就是只用提示词生成。见素材 |
resolution | string | 是 | 1k、2k 或 4k，决定价格 |
aspect_ratio | string | 是 | auto、1:1、3:2、2:3、4:3、3:4、4:5、5:4、9:16、16:9、21:9、4:1、1:4、8:1 或 1:8。auto：只有 1 张参考图时跟随它的比例；多张参考图时由模型决定，不固定跟哪一张，还可能出尺寸表以外的尺寸；没有参考图时按 1:1。需要固定比例请直接传比例 |
num_outputs | integer | 是 | 出几张，1–4。按这个张数冻结，只按生成出来的张数扣费，见价格 |
thinking_level | string | 是 | minimal、medium 或 high |
enable_web_search | boolean | 否 | true 时开启网页搜索，不传为关闭 |
enable_image_search | boolean | 否 | true 时开启图片搜索，不传为关闭 |
seed | integer | 否 | 随机种子，0–2147483647。出多张时第 i 张（从 0 数）用 seed + i，所以 seed + num_outputs - 1 也不能超过 2147483647 |
webhook_url | string | 否 | 任务成功或失败时通知该地址：https，最长 2048 字符，不能指向内网、回环或保留地址。见回调 |
传了其他参数（例如别的图片模型才有的 quality）返回 400 invalid_request，见错误。
2k、16:9，出 2 张：
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8d3f1b6a-2c4e-4f7a-9b1d-6e0a5c3f2b84" \
-d '{
"model": "nano-banana-2.1",
"prompt": "A watercolor fox in a snowy forest",
"resolution": "2k",
"aspect_ratio": "16:9",
"thinking_level": "medium",
"num_outputs": 2
}'响应：200 OK。data 是刚创建的任务，只有下面这几个字段，各字段的含义见创建任务的返回。保存 data.id，用它获取结果。任务创建后仍可能失败（例如余额不够这次的费用），以查询或回调的结果为准。
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jbh4n7c2x5v8b3m6q9w1e4r7",
"model": "nano-banana-2.1",
"status": "queued",
"error": null,
"created_at": "2026-11-01T08:30:00Z"
}
}获取结果
耗时仅供参考（开始生成到出图，不含排队，另加几秒转存；上游忙时会更慢）：1k 约 25 秒，2k 约 35 秒，4k 约 1 分钟，偶尔有 2 分钟以上的慢单。开启搜索没有明显变慢。同一个任务的多张图并行生成，出多张的总耗时和单张差不多。任务结束（成功或失败）后用下面任一方式拿结果：
- 回调（生产环境推荐）：创建时传了
webhook_url，任务结束时会把完整的任务推送一次，见回调。 - 轮询：用
data.id调用GET /v1/tasks/{task_id}，间隔 15 秒以上，直到status为succeeded或failed；多个任务用列出任务的ids一次查询。
上面的请求成功后（省略了其他字段）：
{
"status": "succeeded",
"input": {
"prompt": "A watercolor fox in a snowy forest",
"resolution": "2k",
"aspect_ratio": "16:9",
"thinking_level": "medium"
},
"num_outputs": 2,
"outputs": [
{
"index": 0,
"type": "image",
"url": "https://cdn.nanoapi.ai/h/tk_01jbh4n7c2x5v8b3m6q9w1e4r7_1_1793521800.png",
"preview_url": "https://cdn.nanoapi.ai/h/tk_01jbh4n7c2x5v8b3m6q9w1e4r7_1_1793521800_compressed.jpg"
},
{
"index": 1,
"type": "image",
"url": "https://cdn.nanoapi.ai/h/tk_01jbh4n7c2x5v8b3m6q9w1e4r7_2_1793521800.png",
"preview_url": "https://cdn.nanoapi.ai/h/tk_01jbh4n7c2x5v8b3m6q9w1e4r7_2_1793521800_compressed.jpg"
}
],
"billing": {
"currency": "USD",
"frozen": "…", // 2 × 2k 的每张单价
"charged": "…", // 一样：2 张都生成出来了
"refunded": "0.00",
"billed_seconds": null
}
}| 字段 | Nano Banana 2.1 |
|---|---|
outputs | 每张生成出来的图片一项，最多 num_outputs 项 |
outputs[].type | image |
outputs[].url | PNG 原图，用于下载或查看大图；文件较大（1k 约 1–2 MB，4k 约 30 MB） |
outputs[].preview_url | JPEG 预览图，长边不超过 1024（小图不放大），列表、缩略图请用它。生成不了预览图时为 null |
billing.billed_seconds | 一直是 null：图片按张计费 |
input | 你传的参数；可选的 image_urls、enable_web_search、enable_image_search、seed 传了才有 |
失败时冻结的钱全额退回，原因在 data.error.type，见错误。完整的字段见任务对象。
出图尺寸
宽×高（像素）：2k、4k 正好是 1k 的 2 倍、4 倍。auto 的尺寸取决于参考图，不在表里。
aspect_ratio | 1k | 2k | 4k |
|---|---|---|---|
1:1 | 1024×1024 | 2048×2048 | 4096×4096 |
3:2 | 1264×848 | 2528×1696 | 5056×3392 |
2:3 | 848×1264 | 1696×2528 | 3392×5056 |
4:3 | 1200×896 | 2400×1792 | 4800×3584 |
3:4 | 896×1200 | 1792×2400 | 3584×4800 |
5:4 | 1152×928 | 2304×1856 | 4608×3712 |
4:5 | 928×1152 | 1856×2304 | 3712×4608 |
16:9 | 1376×768 | 2752×1536 | 5504×3072 |
9:16 | 768×1376 | 1536×2752 | 3072×5504 |
21:9 | 1584×672 | 3168×1344 | 6336×2688 |
4:1 | 2064×512 | 4128×1024 | 8256×2048 |
1:4 | 512×2064 | 1024×4128 | 2048×8256 |
8:1 | 2928×352 | 5856×704 | 11712×1408 |
1:8 | 352×2928 | 704×5856 | 1408×11712 |
张数比请求的少
每张图单独生成。有几张没生成出来（例如被内容审核拦下）时，任务仍是 succeeded，outputs 里只有生成出来的那几张，比 num_outputs 少。只按这几张扣费，冻结的其余部分退回（billing.refunded）。一张都没生成出来时任务才是 failed，冻结的钱全额退回：其中只要有 1 张是被内容审核拦下的，失败原因就是 content_policy（不一定每张都被拦，其余几张可能是别的原因），否则一般是 generation_failed。outputs[].index 按生成出来的那几张从 0 连续编号，张数比请求的少时不对应请求里的第几张，不要按它去对位。
素材
参考图以公开的 http(s) 链接放在 image_urls 里提交。不提供上传接口，请自行托管文件。链接最长 4096 字符，必须能直接下载，不能指向 localhost 或内网、回环、保留地址。
参考图（image_urls） | |
|---|---|
| 数量 | 0–14 张（GET /v1/products 的 limits.max_reference_images） |
| 格式 | JPEG、PNG、WebP、AVIF、GIF（取第一帧）、BMP、TIFF。不支持 HEIC / HEIF：iPhone 照片默认是 HEIC，请先转成 JPEG |
| 透明背景 | 透明背景的 PNG 会铺成白底再使用 |
| 有问题时 | 生成时才读取，这时已经冻结过费用：下载不了、格式不支持时任务失败（invalid_media），冻结的钱全额退回 |
任务结束前所有链接都要保持可访问，有有效期的链接也不能提前过期。
在提示词里引用图片
prompt 里写 | 指代 |
|---|---|
@Image1、@Image2… | image_urls 里的图片，按顺序编号 |
- 引用超出了传入的张数（例如只传了 1 张却写了
@Image2，或者没传image_urls却写了@Image）：返回400 invalid_request，param为"prompt"，任务不会创建。 @前面是字母、数字或点的不算引用，所以提示词里写邮箱（例如bob@image2go.com）没有问题。
价格
冻结 = 所选分辨率的每张单价 × num_outputs
扣费 = 所选分辨率的每张单价 × 生成出来的张数正在读取当前价格…
- 只有
resolution影响价格；aspect_ratio、thinking_level、两个搜索开关、seed和参考图都不影响。 - 创建后几秒内按
num_outputs张冻结。成功后按生成出来的张数扣费，其余退回，见张数比请求的少；失败全额退回。
例如上面的请求（2k，num_outputs 为 2）冻结 2 × 2k 的每张单价，2 张都生成出来时扣同样的金额；只生成出 1 张时扣 1 × 2k 的每张单价，另一张的钱退回。冻结和扣费的通用规则见计费。
价格只看请求就能算出来，可以在提交前显示：用 GET /v1/products 返回的当前单价计算（prices 里每个分辨率一行）。价格会调整，不要写死；实际费用以查询任务返回的 billing.frozen 为准。
错误
这个模型特有的错误和失败原因。创建任务的全部错误见创建任务 → 错误，全部失败原因见失败原因。
创建请求出错：请求返回 HTTP 错误，任务不会创建。param 是对应的参数名。
| 状态码 | error.type | 何时出现 | 怎么处理 |
|---|---|---|---|
400 | invalid_request | 少传了必填参数（Field required，param 是缺的那个），或者 prompt 是空的（prompt is required） | 必填参数都要传，见创建任务 |
400 | invalid_request | 提示词引用了没传的图片，param 为 "prompt"（例如 prompt references @Image2, but image_urls has 1 image: use @Image1） | 改正引用，或者把图片加进 image_urls |
400 | invalid_request | resolution、aspect_ratio、thinking_level 不是上面列出的值（例如 Input should be '1k', '2k' or '4k' for nano-banana-2.1），num_outputs 不是 1–4，image_urls 超过 14 张，或者 seed 不在 0–2147483647 之间 | 改成允许的值 |
400 | invalid_request | seed + num_outputs - 1 超过 2147483647，param 为 "seed"（例如 seed must be at most 2147483645 when num_outputs is 3: image i uses seed + i） | 换一个小一点的 seed |
400 | invalid_request | 传了这个模型没有的参数：别的图片模型的参数（quality、variant、background、remove_bg）或视频模型的参数（Extra inputs are not permitted） | 去掉这个参数 |
创建接口的其他错误（401、402、429 等）见创建任务 → 错误。
任务失败：创建请求成功（200），任务之后变成 failed。这种情况没有 HTTP 状态码，原因在任务的 error.type，通过查询任务或回调拿到。
error.type | 何时出现 | 怎么处理 |
|---|---|---|
insufficient_balance | 可用余额不够 num_outputs × 每张单价。创建后几秒内出现，不冻结费用 | 充值或者少出几张，再重新创建 |
spend_limit_exceeded | 加上这个任务的费用会超出 Key 的消费限额。创建后几秒内出现，不冻结费用 | 在控制台 → API Keys 调高限额，或者等限额重置后重新创建 |
invalid_media | 参考图下载不了或读不了（例如 HEIC 照片、文件损坏）。生成时才发现，这时已经冻结过费用，全额退回 | 按 error.message 换掉那张图（HEIC 先转成 JPEG），重新创建 |
content_policy | 一张图都没生成出来，并且至少 1 张是因为提示词或参考图不符合内容政策被拦下的（不一定每张都被拦）。只有部分张被拦下时任务仍然成功，返回其余的张，见张数比请求的少 | 原样重新提交还会失败，请更换提示词或图片 |
generation_failed | 一张图都没生成出来 | 稍后重新创建，或者换一份提示词、图片 |
queue_timeout / internal_error | 排队超过 30 分钟未开始 / 内部错误 | 稍后重新创建 |
所有失败的任务都已全额退回冻结金额，billing.charged 为 "0.00"。