# Nano Banana Pro — /images/generations

图片生成接口（异步任务），承载旗舰级 Nano Banana Pro（Gemini 3 Pro Image）。文生图只需 prompt；图生图把参考图放进 image（可传 URL、data: 或 base64），保留原图主体并按提示词重绘。细节、构图与图中文字排版更强，适合商业封面与高质量插画。提交后立刻返回任务号 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 分辨率，失败不计费。

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

## 认证
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 请求参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型 ID，此处为 nano-banana-pro。 |
| `prompt` | string | 是 | 图片描述提示词。 |
| `size` | string | 否 | 输出比例。推荐直接传宽高比：1:1、3:4、2:3、9:16、4:3、3:2、16:9，模型按该比例原生出图，主体不会被裁切；也兼容像素尺寸（如 1024x1024、1024x1536、1536x1024）。默认 1:1（方图）。 |
| `n` | integer | 否 | 生成数量，默认 1。 |
| `image` | string | 否 | 图生图模式：参考图，可传公网 URL、data: URI 或 base64。提供后即走真正的图生图（保留原图人物/主体），在其基础上按所选 size 比例重绘；等价于调用 /v1/images/edits。 |
| `images` | array | 否 | 多图参考（最多 8 张，建议 ≤4 张以保证主体一致性）：传字符串数组，或 [{"image_url": "..."}] 对象数组；每个元素可为公网 URL、data: URI 或 base64。提供后走多图参考的图生图（融合多张参考图的主体与风格），等价于 /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-pro", "prompt": "a serene ink-wash poster, lots of negative space", "size": "1024x1536"}'
# 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-pro"
}
```

## 图生图（Image-to-Image）
图生图：把参考图放进 image（可传公网 URL、data: URI 或 base64），即走真正的图生图（保留原图人物/主体），在其基础上按所选 size 比例重绘；等价于调用 /v1/images/edits。

```bash
curl https://nezhagate.com/v1/images/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "nano-banana-pro", "prompt": "change the background to a starry sky", "image": "https://example.com/ref.png", "size": "3:4"}'
```

## 生图任务（提交即返回任务号，轮询查结果）
生图通常要 1～3 分钟，所以图片接口统一为异步任务：提交请求会立刻返回任务号 id（HTTP 202），再用任务号轮询查结果——服务端就算重启也会自动续跑，不会丢图。文生图、图生图都一样。（旧的 "async": true 字段已不再需要，传了也会被忽略。）

```bash
# 第 1 步 · 提交任务（立刻返回任务号 id，HTTP 202）
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-pro", "prompt": "an ink-wash poster", "size": "3:4"}'
# 第 2 步 · 轮询查结果（每 2～3 秒查一次，直到 status 变为 succeeded）
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

说明：status 取值为 queued / processing / succeeded / failed。成功后返回里带 data[].url。任务号只能本账户查询。图片接口统一异步——提交即返回任务号；"async": true 仅作向后兼容，可忽略。