# GPT Image 2 图片生成 API（v1 / OpenAI 兼容协议）对接文档

## 概述

本文档描述 **OpenAI 路径兼容**的 GPT Image 2 图片接口，包含两个端点：

| 端点 | 协议 | 说明 |
|---|---|---|
| `POST /v1/images/generations` | **异步**（默认）/ 同步 | 文生图 / 图生图 |
| `POST /v1/images/edits` | **异步**（默认）/ 同步 | 图片编辑（上传文件） |

两个端点的请求体沿用 OpenAI `images/generations`、`images/edits` 的字段名，便于从其它平台迁移。

**协议形态由 `async` 参数决定，默认异步：**

- **异步（默认，`async` 不传或传 `true`）**：创建任务后立即返回平台统一任务体
  （`{code,msg,data:{taskId,...}}`），拿到 `data.taskId` 后轮询 `GET /v1/images/generations/{taskId}`。
  此形态**不能**直接用 OpenAI SDK 的 `images.generate()` / `images.edit()` 解析返回值。
- **同步（`async=false`）**：服务端阻塞等待出图，直接返回 OpenAI 标准图片响应
  （`{created,data:[{url}]}`），**可直接用 OpenAI SDK 解析**。适合迁移已有的 OpenAI 调用代码。

> 生成大图（4K）时耗时较长，同步模式请把客户端超时放宽到 10 分钟以上；
> 批量生产场景建议用默认的异步模式，避免长时间占用连接。

**Base URL**: `https://api.apiverse.ai`

---

## 认证方式

在请求头中携带 API Key 进行认证（与 v2 接口共用同一套密钥）：

```
Authorization: Bearer {YOUR_API_KEY}
```

---

## 快速开始

### cURL 示例

**文生图**
```bash
curl -X POST "https://api.apiverse.ai/v1/images/generations" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A beautiful sunset over the ocean, oil painting style",
    "size": "1792x1024"
  }'
```

**图生图**
```bash
curl -X POST "https://api.apiverse.ai/v1/images/generations" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Transform this image into watercolor style",
    "image": ["https://example.com/reference.jpg"],
    "size": "1024x1024"
  }'
```

**查询任务结果**
```bash
curl "https://api.apiverse.ai/v1/images/generations/task_20260509150000_abc12345" \
  -H "Authorization: Bearer your_api_key_here"
```

---

## 接口说明

### 创建图片生成任务

**POST** `/v1/images/generations`

**Content-Type**: `application/json`

> **协议说明**：默认异步——建单后立即返回 `taskId`（通常 1 秒内），不阻塞等待出图，
> 请用 `GET /v1/images/generations/{taskId}` 轮询，或用 `callback_url` 接收完成回调。
> 需要一次请求拿到图片时传 `async=false`，见下文「同步模式」。

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| model | string | 是 | 模型 ID，取值：`gpt-image-2`、`gpt-image-2-official`、`gpt-image-2-pro` |
| prompt | string | 是 | 图片描述提示词，最多 20,000 字符（`gpt-image-2-official` 为 32,000） |
| image | string[] | 否 | 输入图片列表（URL 或 Base64 data URI）。**传入该字段即自动按图生图处理** |
| mask | string | 否 | 蒙版图（URL 或 Base64 data URI），需与 `image` 一起使用，用于局部重绘 |
| size | string | 否 | 画面比例或尺寸：可传 `16:9` 这类比例串，也可传 `1024x1024`、`1792x1024` 这类像素串（服务端按宽高比就近匹配标准比例），还可直接传 `1K`/`2K`/`4K` 指定清晰度 |
| resolution | string | 否 | 分辨率档 `1k` / `2k` / `4k`，**优先级高于 `size` 里的档位与 `quality`** |
| n | int | 否 | 生成数量，默认 1，取值 1–10（`gpt-image-2-official` 为 1–4） |
| quality | string | 否 | 质量档；`high` 在未传 `resolution` 且 `size` 不是档位串时升到 2K。`gpt-image-2-official` 取值 `auto`（默认）/`low`/`medium`/`high` |
| background | string | 否 | **仅 `gpt-image-2-official`**：背景处理，取值 `auto`（默认）/`opaque`/`transparent`。`transparent` 需搭配 `output_format=png` |
| moderation | string | 否 | **仅 `gpt-image-2-official`**：内容审核强度，取值 `auto`（默认）/`low`。与 `nsfw_check=true` 同传时强制为 `auto` |
| output_format | string | 否 | **仅 `gpt-image-2-official`**：输出图片格式，取值 `png`（默认）/`jpeg` |
| output_compression | int | 否 | **仅 `gpt-image-2-official`**：输出压缩率 0–100，仅在 `output_format=jpeg` 时生效 |
| nsfw_check | boolean | 否 | 安全审核开关；与 `extra_body.nsfw_checker` 同传时以本字段为准 |
| async | boolean | 否 | 协议形态，默认 `true`（异步返回 `taskId`）；传 `false` 阻塞至出图并返回 OpenAI 标准图片响应 |
| response_format | string | 否 | **仅 `async=false` 时生效**：`url`（默认）或 `b64_json` |
| extra_body | object | 否 | 模型私有参数，如 `{"nsfw_checker": true}` |
| callback_url | string | 否 | 任务完成后的回调通知 URL |
| task_nickname | string | 否 | 任务昵称，便于业务侧标记 |
| user | string | 否 | 调用方用户标识（OpenAI 兼容字段） |

> **关于 `size` 的换算**：服务端会把 `WxH` 尺寸换算成最接近的标准宽高比，候选比例为
> `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `21:9`。例如 `1792x1024` → `16:9`，`1024x1024` → `1:1`。
> 未传 `size` 时使用模型默认比例。
>
> `gpt-image-2-official` 走独立的比例表，支持
> `1:1` / `3:2` / `2:3` / `4:3` / `3:4` / `5:4` / `4:5` / `16:9` / `9:16` / `2:1` / `1:2` / `3:1` / `1:3` / `21:9` / `9:21`，
> 也可直接传该比例表内的像素串（如 `1536x864`、`3840x2160`），未命中时报 `size 不支持`。

> **关于输出分辨率**：分辨率档优先级为 `resolution` > `size` 里的档位串 > `quality`。
> 例如 `{"size":"16:9","resolution":"4k"}` 得到 16:9 的 4K 图；只传 `{"size":"2K"}` 得到默认比例的 2K 图；
> 都不传时默认 1K。不同分辨率档计价不同。

> **关于 `gpt-image-2-official`**：该模型按 token 计费（提示词 token + 参考图 token + 出图 token），
> 建单时按预估用量冻结额度，任务完成后按实际用量结算，查询结果返回完整 `usage`（见「查询图片任务」）；参考图最多 16 张，
> `mask` 必须与 `image` 一起传。

#### 请求示例

**文生图：**
```json
{
  "model": "gpt-image-2",
  "prompt": "A beautiful sunset over the ocean, oil painting style",
  "size": "1792x1024"
}
```

**图生图：**
```json
{
  "model": "gpt-image-2",
  "prompt": "Transform this image into watercolor style",
  "image": ["https://example.com/reference.jpg"],
  "size": "1024x1024"
}
```

**指定比例 + 分辨率档：**
```json
{
  "model": "gpt-image-2",
  "prompt": "A surreal painting of a giant banana floating in space",
  "size": "16:9",
  "resolution": "4k"
}
```

**gpt-image-2-official（透明背景 + PNG 输出）：**
```json
{
  "model": "gpt-image-2-official",
  "prompt": "A minimal logo of a paper crane, centered, clean edges",
  "size": "1:1",
  "resolution": "2k",
  "quality": "high",
  "background": "transparent",
  "output_format": "png"
}
```

**gpt-image-2-official（JPEG 输出 + 压缩）：**
```json
{
  "model": "gpt-image-2-official",
  "prompt": "Product photo of a ceramic mug on a wooden table",
  "size": "3:2",
  "output_format": "jpeg",
  "output_compression": 80,
  "moderation": "low"
}
```

#### 响应参数（建单成功）

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.taskId | string | 任务 ID，用于查询任务状态 |
| data.status | string | 任务状态，建单时固定为 `processing` |
| data.createdAt | string | 创建时间 |

#### 响应示例（建单成功）

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260509150000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-09 15:00:00"
  }
}
```

---

### 图片编辑

**POST** `/v1/images/edits`

**Content-Type**: `multipart/form-data`

在给定一张或多张原图与提示词的情况下，对图片进行编辑 / 重绘 / 扩展。接口路径与请求字段对齐 OpenAI
`images/edits` 协议，原图以文件形式上传（无需先转 URL 或 Base64）。

> **协议说明**：默认异步——建单后立即返回 `taskId`，不阻塞等待出图，
> 请用 `GET /v1/images/generations/{taskId}` 轮询查询结果，与生成接口共用同一个查询端点。
> 传 `async=false` 可改为同步返回图片，见下文「同步模式」。

### cURL 示例

```bash
curl -X POST "https://api.apiverse.ai/v1/images/edits" \
  -H "Authorization: Bearer your_api_key_here" \
  -F "model=gpt-image-2" \
  -F "prompt=给猫戴上一顶生日帽" \
  -F "size=1024x1024" \
  -F "image=@/path/to/cat.png"
```

多张参考图 + 蒙版：

```bash
curl -X POST "https://api.apiverse.ai/v1/images/edits" \
  -H "Authorization: Bearer your_api_key_here" \
  -F "model=gpt-image-2" \
  -F "prompt=把这两张图合成到同一个场景" \
  -F "n=2" \
  -F "image=@/path/to/img1.png" \
  -F "image=@/path/to/img2.png" \
  -F "mask=@/path/to/mask.png"
```

`gpt-image-2-official` + 扩展参数：

```bash
curl -X POST "https://api.apiverse.ai/v1/images/edits" \
  -H "Authorization: Bearer your_api_key_here" \
  -F "model=gpt-image-2-official" \
  -F "prompt=把背景抠掉，只保留主体" \
  -F "size=1:1" \
  -F "resolution=2k" \
  -F "background=transparent" \
  -F "output_format=png" \
  -F "image=@/path/to/product.png"
```

### 请求参数（multipart/form-data）

本端点与 `/v1/images/generations` 走同一条链路，**字段名与含义完全一致**，
差别只在于原图/蒙版以文件上传，而不是 URL / Base64。因此上面表格里的参数在这里同样可用
（包括 `gpt-image-2-official` 的 `background` / `moderation` / `output_format` / `output_compression`）。

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| model | string | 是 | 模型 ID，取值：`gpt-image-2`、`gpt-image-2-official`、`gpt-image-2-pro` |
| prompt | string | 是 | 编辑指令提示词 |
| image | file | 是 | 待编辑的原图（二进制）。多张时重复传 `image` 字段即可 |
| mask | file | 否 | 蒙版图（二进制）。蒙版中透明区域表示需要编辑的部位 |
| n | int | 否 | 生成数量，默认 1。**按生成数量计费** |
| size | string | 否 | 画面比例或尺寸，如 `16:9`、`1024x1024`，取值同生成接口 |
| resolution | string | 否 | 分辨率档 `1k` / `2k` / `4k` |
| quality | string | 否 | 质量档，取值同生成接口 |
| background | string | 否 | **仅 `gpt-image-2-official`**：`auto` / `opaque` / `transparent` |
| moderation | string | 否 | **仅 `gpt-image-2-official`**：`auto` / `low` |
| output_format | string | 否 | **仅 `gpt-image-2-official`**：`png` / `jpeg` |
| output_compression | int | 否 | **仅 `gpt-image-2-official`**：0–100，仅 `jpeg` 生效 |
| nsfw_check | boolean | 否 | 安全审核开关，传 `true` / `false` |
| async | boolean | 否 | 协议形态，默认 `true`（异步返回 `taskId`）；传 `false` 阻塞至出图并返回 OpenAI 标准图片响应 |
| response_format | string | 否 | **仅 `async=false` 时生效**：`url`（默认）或 `b64_json` |
| extra_body | string | 否 | 模型私有参数，传 JSON 字符串，如 `{"nsfw_checker":true}` |
| image_urls | string | 否 | 以 URL 形式追加参考图（可重复传），与上传文件可混用 |
| mask_url | string | 否 | 以 URL 形式提供蒙版图，未上传 `mask` 文件时生效 |
| callback_url | string | 否 | 任务完成后的回调通知 URL |
| task_nickname | string | 否 | 任务昵称，便于业务侧标记 |
| user | string | 否 | 调用方用户标识（OpenAI 兼容字段） |

> 各模型对 `n`、参考图张数、`size` 取值的限制与生成接口一致（如 `gpt-image-2-official` 的
> `n` 为 1–4、参考图最多 16 张），超限时在建单响应里返回 `code=10002` 与具体原因。

### 响应参数（建单成功）

与 `/v1/images/generations` 完全一致：

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.taskId | string | 任务 ID，用于查询任务状态 |
| data.status | string | 任务状态，建单时固定为 `processing` |
| data.createdAt | string | 创建时间 |

### 响应示例（建单成功）

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260509150000_abc12345",
    "status": "processing",
    "createdAt": "2026-05-09 15:00:00"
  }
}
```

---

### 查询图片任务

**GET** `/v1/images/generations/{taskId}`

`/v1/images/generations` 与 `/v1/images/edits` 创建的任务都用本端点查询。
任务处于 `processing` 时请按「最佳实践」中的策略轮询，直到 `success` 或 `failed`。

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260509150000_abc12345",
    "status": "success",
    "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/09/output_001.png"],
    "progress": 100,
    "createdAt": "2026-05-09 15:00:00",
    "updatedAt": "2026-05-09 15:00:25"
  }
}
```

> 同一任务也可用 `GET /api/v2/open/aigc/{taskId}` 查询，返回结构一致。

#### `gpt-image-2-official` 的 token 用量

`model=gpt-image-2-official` 的任务成功后，查询响应在上面字段之外额外返回：

| 字段 | 类型 | 说明 |
|-----|------|------|
| data.output | object | 清洗后的官方完整响应。官方 `b64_json` 会落盘并替换成对应 URL，其余字段及完整 `usage` 原样保留 |
| data.completionTokens | int | 本次结算的实际总 token 数，等于 `output.usage.total_tokens` |

其它模型不返回这两个字段。

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260509150000_abc12345",
    "status": "success",
    "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/09/output_001.png"],
    "progress": 100,
    "createdAt": "2026-05-09 15:00:00",
    "updatedAt": "2026-05-09 15:00:25",
    "output": {
      "created": 1787661600,
      "data": [{ "url": "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/09/output_001.png" }],
      "background": "opaque",
      "output_format": "png",
      "quality": "high",
      "size": "1024x1024",
      "usage": {
        "input_tokens": 10,
        "input_tokens_details": { "cached_tokens": 0, "text_tokens": 10, "image_tokens": 0 },
        "output_tokens": 7033,
        "output_tokens_details": { "text_tokens": 0, "image_tokens": 7033 },
        "total_tokens": 7043
      }
    },
    "completionTokens": 7043
  }
}
```

`usage` 字段含义：

| 字段 | 说明 |
| --- | --- |
| `input_tokens` | 输入 token 总数 |
| `input_tokens_details.cached_tokens` | 缓存命中的输入 token |
| `input_tokens_details.text_tokens` | 提示词 token |
| `input_tokens_details.image_tokens` | 参考图 token；文生图通常为 0 |
| `output_tokens` | 输出 token 总数 |
| `output_tokens_details.image_tokens` | 生成图片 token |
| `output_tokens_details.text_tokens` | 输出文本 token，图片生成通常为 0 |
| `total_tokens` | 总 token 数 |

> 计费以 `output.usage` 为准：建单时按预估用量冻结，完成后按实际的文本输入 / 图片输入 / 图片输出 token 多退少补，失败任务全额解冻。
>
> 少数情况下只能拿到总量、拿不到细分，此时 `input_tokens_details` / `output_tokens_details` 可能为 0 或整体缺省，
> 而 `input_tokens` / `output_tokens` / `total_tokens` 始终按实际结算口径返回。请按可选字段做兼容解析。

#### 错误响应

**异步模式**（默认）下两个端点的错误都沿用平台统一错误体（HTTP 状态码恒为 200，以 `code` 判断）；
同步模式（`async=false`）的错误体见下文「同步模式」。

```json
{
  "code": 10002,
  "msg": "参数错误: resolution 仅支持 1K、2K、4K"
}
```

| code | 说明 |
|------|------|
| 0 | 成功 |
| 10002 | 参数缺失或格式错误 / 不支持的 model |
| 10005 | API Key 无效或缺失 |
| 30003 | 任务不存在 |
| 40001 | 余额不足 |
| 90003 | 服务器内部错误 |

任务本身失败（如内容不符合规范）不体现在建单响应里，而是查询时 `data.status` 为 `failed`，
并带 `data.errorCode` / `data.errorMsg`。

---

## 同步模式（`async=false`）

两个端点都支持传 `async=false` 切换为同步：服务端阻塞等待出图，直接返回 OpenAI 标准图片响应。

```bash
curl -X POST "https://api.apiverse.ai/v1/images/generations" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A beautiful sunset over the ocean, oil painting style",
    "size": "16:9",
    "async": false
  }'
```

响应体（与异步模式完全不同，这是 OpenAI 标准图片响应）：

```json
{
  "created": 1778394000,
  "data": [
    { "url": "https://.../output_001.png" }
  ]
}
```

传 `response_format=b64_json` 时 `data` 项改为 `{"b64_json":"..."}`。

**同步模式的错误响应**沿用 OpenAI 标准错误体，并使用真实 HTTP 状态码（不再恒为 200）：

```json
{
  "error": {
    "message": "参数错误: resolution 仅支持 1K、2K、4K",
    "type": "invalid_request_error"
  }
}
```

| HTTP | type | 说明 |
|------|------|------|
| 400 | `invalid_request_error` | 参数缺失或格式错误 / 不支持的 model |
| 401 | `authentication_error` | API Key 无效或缺失 |
| 402 | `insufficient_quota` | 余额不足 |
| 500 | `generation_error` | 任务执行失败（如内容不符合规范） |
| 504 | `timeout_error` | 等待超过 10 分钟仍未出图；**任务未取消**，`error.code` 即 `taskId`，可继续用查询端点取结果 |

---

## Python 接入示例

### 异步（默认，推荐）

拿到 `data.taskId` 后轮询 `GET /v1/images/generations/{taskId}`：

```python
import requests, time

base = "https://api.apiverse.ai"
headers = {"Authorization": "Bearer your_api_key_here"}

def wait_result(task_id):
    while True:
        data = requests.get(f"{base}/v1/images/generations/{task_id}", headers=headers).json()["data"]
        if data["status"] != "processing":
            return data
        time.sleep(3)

# 文生图 / 图生图
task_id = requests.post(
    f"{base}/v1/images/generations",
    headers=headers,
    json={
        "model": "gpt-image-2",
        "prompt": "A beautiful sunset over the ocean, oil painting style",
        "size": "16:9",
        "resolution": "2k",
    },
).json()["data"]["taskId"]
print(wait_result(task_id).get("result"))

# 图片编辑（上传文件）
with open("/path/to/cat.png", "rb") as f:
    task_id = requests.post(
        f"{base}/v1/images/edits",
        headers=headers,
        data={"model": "gpt-image-2", "prompt": "给猫戴上一顶生日帽", "size": "1024x1024"},
        files={"image": f},
    ).json()["data"]["taskId"]
print(wait_result(task_id).get("result"))
```

### 同步（OpenAI SDK 直连）

`async=false` 时响应体即 OpenAI 标准格式，可直接用官方 SDK。`async` 走 `extra_body` 传入：

```python
from openai import OpenAI

client = OpenAI(
    api_key="your_api_key_here",
    base_url="https://api.apiverse.ai/v1",
    timeout=900,  # 同步模式需放宽超时
)

# 文生图
img = client.images.generate(
    model="gpt-image-2",
    prompt="A beautiful sunset over the ocean, oil painting style",
    size="1024x1024",
    extra_body={"async": False, "resolution": "2k"},
)
print(img.data[0].url)

# 图片编辑
with open("/path/to/cat.png", "rb") as f:
    edited = client.images.edit(
        model="gpt-image-2",
        prompt="给猫戴上一顶生日帽",
        image=f,
        extra_body={"async": False},
    )
print(edited.data[0].url)
```

---

## 最佳实践

### 1. 超时设置

异步模式（默认）下两个端点均建单即返回，客户端超时按普通接口设置即可（图片编辑需考虑上传原图的耗时）。
同步模式（`async=false`）需把客户端超时放宽到 10 分钟以上；服务端等待超过 10 分钟会返回 504，
此时任务未取消，可用 `error.code` 里的 `taskId` 继续查询。

### 2. 轮询策略

（异步模式）建议：前 30 秒每 3 秒查询一次，30 秒后每 5 秒一次。
生产环境建议改用 `callback_url` 回调，可显著降低查询请求量。

### 3. Prompt 编写建议

- 使用清晰、具体的描述
- 可指定艺术风格（如 oil painting、watercolor、digital art 等）
- 图生图时，prompt 应描述希望对原图进行的变换
- 支持多语言，但英文效果通常更好