# GPT Image 2 Official 图片生成 API

## 概述

`gpt-image-2-official` 是 OpenAI 官方 `gpt-image-2` 的异步别名。本页仅介绍模型专属的 v2 接口：

- 创建：`POST /api/v2/open/aigc/gpt-image-2-official`
- 查询：`GET /api/v2/open/aigc/{taskId}`
- 请求字段使用 camelCase

- 支持文生图、图生图和带蒙版的局部重绘
- 支持最多 16 张参考图、单次生成 1–4 张图片
- 支持 15 种画面比例以及 1K / 2K / 4K 分辨率档位
- 支持 PNG / JPEG；PNG 可生成透明背景
- 按上游实际 token 用量结算，查询结果返回完整 `usage`
- 查询结果的 `output` 包含清洗后的官方完整响应；图片 Base64 会转换为 URL

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

## 认证

```http
Authorization: Bearer YOUR_API_KEY
```

## 创建任务

**POST** `/api/v2/open/aigc/gpt-image-2-official`

与其他 v2 模型接口风格一致：路径即模型，请求体不需要 `model` 字段，字段名为 camelCase。

### 文生图示例

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gpt-image-2-official" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "浅色木桌上的蓝色陶瓷花瓶，极简产品摄影，柔和自然光，纯净背景",
    "size": "16:9",
    "resolution": "2k",
    "quality": "high",
    "n": 1,
    "outputFormat": "jpeg",
    "outputCompression": 90,
    "callbackUrl": "https://example.com/webhooks/image",
    "taskNickname": "autumn-fox"
  }'
```

### 图生图示例

```json
{
  "prompt": "保留主体，将背景替换为极简摄影棚，并输出透明 PNG",
  "imageUrls": ["https://example.com/product.png"],
  "size": "1:1",
  "resolution": "1k",
  "background": "transparent",
  "outputFormat": "png"
}
```

### 蒙版局部重绘示例

```json
{
  "prompt": "仅把蒙版区域替换为一束白色鲜花",
  "imageUrls": ["https://example.com/room.png"],
  "maskUrl": "https://example.com/mask.png",
  "size": "1:1",
  "resolution": "1k",
  "outputFormat": "png"
}
```

创建成功后立即返回异步任务 ID：

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_xxx",
    "status": "processing",
    "createdAt": "2026-08-25 18:00:00"
  }
}
```

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `prompt` | string | 是 | 图片描述，最长 32,000 个字符 |
| `n` | integer | 否 | 图片数量，范围 1–4，默认 1 |
| `size` | string | 否 | 画面比例、像素尺寸或 `auto`，默认 `1:1`；详见下方映射表 |
| `resolution` | string | 否 | `1k`、`2k` 或 `4k`，默认 `1k`；与比例型 `size` 组合使用 |
| `quality` | string | 否 | `auto`、`low`、`medium`、`high`，默认 `auto` |
| `imageUrls` | string[] | 否 | 参考图，最多 16 张；支持图片 URL，也可直接传 Base64 data URI |
| `base64File` | string | 否 | 单张 Base64 参考图，排在参考图列表**最前** |
| `base64FileList` | string[] | 否 | 多张 Base64 参考图，追加到参考图列表**末尾** |
| `maskUrl` | string | 否 | 蒙版 PNG URL，必须和参考图一起使用，尺寸须与首张参考图一致且包含 Alpha 通道 |
| `maskFile` | string | 否 | 蒙版 Base64；与 `maskUrl` 同传时以 `maskFile` 为准 |
| `background` | string | 否 | `auto`、`opaque` 或 `transparent`，默认 `auto`；透明背景只支持 PNG |
| `moderation` | string | 否 | `auto` 或 `low`，默认 `auto` |
| `nsfwCheck` | boolean | 否 | 安全审核开关；为 `true` 时强制使用 `moderation=auto`，默认 `false` |
| `outputFormat` | string | 否 | `png` 或 `jpeg`，默认 `png`；当前渠道不支持 WebP |
| `outputCompression` | integer | 否 | JPEG 输出压缩质量，范围 0–100；PNG 不支持压缩，请勿传该字段 |
| `user` | string | 否 | 用于识别终端用户的稳定标识 |
| `callbackUrl` | string | 否 | 任务完成后的回调地址 |
| `taskNickname` | string | 否 | 任务昵称，便于业务侧追踪 |

> **参考图三种传法任选其一**：`imageUrls` 本身既能放 URL 也能放 Base64 data URI，`base64File` / `base64FileList` 只是为对齐其他 v2 接口的习惯而保留。三者可同传，最终顺序固定为 `base64File` → `imageUrls` → `base64FileList`；蒙版重绘以**首张**参考图为基准，混用时请注意顺序。

> **snake_case 别名**：本接口同时接受 `image_urls`、`mask_url`、`output_format`、`output_compression`、`nsfw_check`、`callback_url`、`task_nickname`。两种写法同传时以 camelCase 为准。

### 尺寸与分辨率映射

`size × resolution` 会在网关内转换为上游像素尺寸：

| `size` | `1k` | `2k` | `4k` |
| --- | --- | --- | --- |
| `1:1` | 1024×1024 | 2048×2048 | 2880×2880 |
| `3:2` | 1536×1024 | 2048×1360 | 3520×2336 |
| `2:3` | 1024×1536 | 1360×2048 | 2336×3520 |
| `4:3` | 1024×768 | 2048×1536 | 3312×2480 |
| `3:4` | 768×1024 | 1536×2048 | 2480×3312 |
| `5:4` | 1280×1024 | 2560×2048 | 3216×2576 |
| `4:5` | 1024×1280 | 2048×2560 | 2576×3216 |
| `16:9` | 1536×864 | 2048×1152 | 3840×2160 |
| `9:16` | 864×1536 | 1152×2048 | 2160×3840 |
| `2:1` | 2048×1024 | 2688×1344 | 3840×1920 |
| `1:2` | 1024×2048 | 1344×2688 | 1920×3840 |
| `3:1` | 1536×512 | 3072×1024 | 3840×1280 |
| `1:3` | 512×1536 | 1024×3072 | 1280×3840 |
| `21:9` | 2016×864 | 2688×1152 | 3840×1648 |
| `9:21` | 864×2016 | 1152×2688 | 1648×3840 |

也可以直接把表中的像素尺寸作为 `size` 传入。`size=auto` 当前按 `1:1` 处理。

## 查询任务

**GET** `/api/v2/open/aigc/{taskId}`

```bash
curl "https://api.apiverse.ai/api/v2/open/aigc/task_xxx" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

`status` 可能为 `processing`、`success` 或 `failed`。建议每 2–5 秒查询一次，直到进入终态。

成功时，`result` 是图片 URL 列表，`output` 是清洗后的官方响应。官方 `b64_json` 会落盘并替换成对应 URL，其余字段及完整 `usage` 原样保留。

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_xxx",
    "status": "success",
    "result": ["https://cdn.example.com/image.png"],
    "output": {
      "created": 1787661600,
      "data": [{"url": "https://cdn.example.com/image.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
      }
    }
  }
}
```

### 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 数 |

## 回调与计费

传入 `callbackUrl` 后，任务进入 `success` 或 `failed` 终态时，网关会发送 HTTP POST 回调。

系统创建任务时按参数预冻结，成功后依据 `output.usage` 中的文本输入、图片输入和图片输出 token 多退少补；失败任务解冻。