# Nano Banana 2.1 — /images/generations

图片生成接口（异步任务），承载 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 宽幅也能直接出图。按张计费，失败不计费。

**端点:** `POST https://nezhagate.com/v1/images/generations`

## 快速开始

三步跑通：提交任务 → 查询结果 → 拿到图片链接。把 YOUR_API_KEY 换成你的 Key，下面的命令可以直接运行。

第 1 步 · 提交任务（立刻返回任务号，HTTP 202）

```bash
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"}'
```

返回（HTTP 202）

```json
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281500,
  "model": "nano-banana-2.1"
}
```

第 2 步 · 每 2～3 秒查询一次，直到 status 变成 succeeded 或 failed

```bash
curl https://nezhagate.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

成功时的返回

```json
{
  "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 天；需要长期使用，请下载到你自己的存储。

### 完整示例（Python：提交 → 等待 → 保存到本地）

```python
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
```

## 请求参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `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 字段。 |

## 请求示例
```bash
# 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'
```

## 响应示例
```json
{
  "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 天。

**两张参考图的图生图**

```bash
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 文档](https://nezhagate.com/docs/webhooks)

```bash
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"}'
```