# Banana 2 · ImgAPI 原生 API

- 模型 ID：nano-banana-2
- 基础地址：https://imgapi.vip/prod-api
- 鉴权：提交与查询都在 JSON 的 `key` 字段传 16 位 API Key。把示例占位符替换成自己的 Key，程序中从 `IMGAPI_CARD_KEY` 环境变量读取。

## 提交任务

```bash
curl --request POST 'https://imgapi.vip/prod-api/tool/imgapi/draw/Async' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "key": "你的16位Key",
  "model": "nano-banana-2",
  "prompt": "白底运动鞋商品主图，柔和棚拍光线",
  "aspectRatio": "1:1",
  "quality": "auto",
  "resolution": "2K"
}'
```

收到响应后立即保存任务 ID（`id` 或 `task_id`）。`submitted` 表示已受理。

```json
{"id":"示例任务ID","task_id":"示例任务ID","status":"submitted","code":200,"used_points":8}
```

## 查询结果

把下方 `id` 换成提交返回的任务 ID，每 2 秒查询同一个任务。读取响应顶层或 `data` 中的任务对象。先确认 `id` 对应原任务，再根据 `status` 判断结果。已退款的响应可能带业务 `code: 400`，此时仍应识别 `status: refunded`。没有可识别的任务状态时，按 HTTP 或业务错误处理。

```bash
curl --request POST 'https://imgapi.vip/prod-api/tool/gptimage2/query' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "key": "你的16位Key",
  "id": "提交接口返回的任务 ID"
}'
```

- `submitted` / `processing`：继续查询原任务。查询遇到 429 时按 Retry-After 或稍后再查。
- `succeeded`：读取非空的 `image`，用 GET 下载原文件并按实际格式保存。
- `failed` / `refunded`：停止轮询。记录任务 ID 和 `failure_reason`（如有）。若返回 `refunded_points`，可结合使用记录核对退款。

```json
{"id":"示例任务ID","status":"succeeded","image":"https://example.com/generated.png","code":200,"image_expires_at":"2026-11-17 16:00:00"}
```

客户端可设 10 分钟轮询上限。超时后保留任务 ID，后续继续查同一任务。提交超时且未拿到 ID 时先核对使用记录。再次提交会创建新任务，可能重复扣费。

## 输入限制与参数

- 参考图文件格式：JPG / PNG / WebP
- 参考图单张体积上限：10 MB
- `prompt`（string，必填）：图片描述，最多 10,000 个字符。
- `resolution`（string，可选）：可选 1K / 2K / 4K，输出宽高以实际图片为准。 默认值：2K。
- `quality`（string，可选）：推荐填写 auto，其他质量值的效果尚未验证。 默认值：auto。
- `aspectRatio`（string，可选）：auto 使用模型默认构图。可选 1:1、3:2、2:3、16:9、9:16、4:3、3:4、21:9、9:21、1:3、3:1、2:1、1:2。 默认值：auto。
- `urls`（string[]，图生图必填）：字符串数组，每个元素是一张参考图的链接或完整 Base64 数据 URI。最多 12 张，例如 ["https://example.com/reference.png"]。文生图可省略或传空数组。
- `storageDays`（string，可选）：可选 0、7、30。保存 7 天或 30 天，每张分别加收 1 或 2 积分。 默认值：0。
- `webhook`（string，可选）：接收任务完成通知的 HTTP 或 HTTPS 地址。省略时请主动查询。

按成功图片扣积分。示例档位 2K 的基础价格为 8 积分/张。其他档位、保存时长和渠道可能影响扣费，以页面价格和使用记录为准。
