# GPT Image 2 API 文档

本服务提供 OpenAI 兼容的图像生成接口，可直接用 `openai` Python / Node SDK 调用，只需把 `base_url` 指向本站。

## 基础信息

- **Base URL**：`https://<你的部署域名>/v1`（在浏览器里打开本站时即为 `location.origin + "/v1"`）
- **鉴权**：HTTP `Authorization: Bearer <你的 Token>`。Token 在「个人中心」获取。
- **计费**：所有调用按积分扣费。1 积分 = ¥0.10。
- **限制**：参考图（edits）最多 6 张，所有图片合计大小 < 3.5 MB；单次最多生成 4 张图。

请求体均为 `application/json`（生成）或 `multipart/form-data`（编辑）。

---

## POST `/v1/images/generations`

文本生图。

请求体字段：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `gpt-image-2` 或 `nano-banana-3` |
| `prompt` | string | 是 | 自然语言描述，建议 < 1500 字符 |
| `aspect_ratio` | string | 否 | `auto`/`16:9`/`9:16`/`1:1`/`4:3`/`3:4`/`3:2`/`2:3`/`16:10`/`10:16`/`5:4`/`4:5` |
| `n` | int | 否 | 生成张数，默认 1，最大 4 |
| `quality` | string | 否 | `low` / `medium` / `high` / `auto`，默认 `auto` |
| `size` | string | 否 | `1K` / `2K` / `4K`，与 quality 共同决定计费阶 |
| `response_format` | string | 否 | `url`（默认）或 `b64_json` |
| `background` | bool | 否 | true 时异步返回 `{id,status:"pending"}`，需轮询 jobs |

同步成功响应：

```json
{
  "data": [
    {"url": "/img/gen_xxxx/0.png", "mirror_url": "/img/gen_xxxx/0.png", "bytes": 234567}
  ],
  "usage": {"credits_charged": 20}
}
```

---

## POST `/v1/images/edits`

带参考图的生图（image-to-image / inpaint）。`multipart/form-data` 上传，字段同 generations，额外有：

| 字段 | 说明 |
| --- | --- |
| `image[]` | 1–6 个文件域，PNG / JPEG / WEBP，单文件 ≤ 3.5 MB，合计 ≤ 3.5 MB |
| `mask` | 可选，与 image 同分辨率的 alpha 蒙版，目前仅 `gpt-image-2` 支持 |

其它字段（`model`/`prompt`/`aspect_ratio`/`n`/`quality`/`response_format`/`background`）与 generations 一致，用表单字段而非 JSON。

---

## GET `/v1/images/jobs/:id`

轮询异步任务（在 `background:true` 时使用）。建议 1–2s 一次。

响应：

```json
{
  "id": "gen_xxxx",
  "status": "succeeded",
  "result": {
    "data": [{"url": "/img/gen_xxxx/0.png", "mirror_url": "/img/gen_xxxx/0.png", "bytes": 234567}],
    "usage": {"credits_charged": 20}
  }
}
```

`status` 取值：`pending` / `succeeded` / `failed`。失败时 `result` 替换为 `{"error":"…"}`。

---

## Python (OpenAI SDK) 示例

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://你的站点/v1",
    api_key="sk-你的Token",
)

resp = client.images.generate(
    model="gpt-image-2",
    prompt="一只戴着围巾的柴犬，赛博朋克霓虹街景",
    n=1,
    size="2K",
    quality="high",
)
print(resp.data[0].url)
```

## curl 示例

```bash
curl https://你的站点/v1/images/generations \
  -H "Authorization: Bearer sk-你的Token" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"赛博朋克猫","n":1,"quality":"high","size":"2K"}'
```

---

## 价格表（积分）

| 画质 \ 尺寸 | 1K | 2K | 4K |
| --- | ---: | ---: | ---: |
| low（标准） | 5 | 15 | 40 |
| medium（高） | 10 | 30 | 80 |
| high（极高） | 20 | 60 | 160 |

`n` 张图的成本 = 表格值 × n。`quality:auto` 会按 prompt 实际匹配到 `medium`。

---

## 错误码

| HTTP | detail | 说明 |
| --- | --- | --- |
| 401 | `invalid_api_key` | Token 缺失或无效 |
| 402 | `insufficient_credits` | 余额不足，请去「充值」页 |
| 400 | `invalid_request` | 字段非法（如 aspect_ratio / n / quality 取值越界） |
| 413 | `payload_too_large` | 参考图合计 > 3.5 MB |
| 429 | `rate_limited` | 当前账号触发限流，稍后重试 |
| 502 | `upstream_unavailable` | 上游图像引擎暂时不可用，建议指数退避重试 |
| 500 | `internal_error` | 服务端异常，请记录请求 ID 反馈给管理员 |

错误响应统一为：

```json
{"detail": "insufficient_credits", "message": "余额不足，请前往充值"}
```