# 图片生成 API（统一入口）对接文档

## 概述

统一图片生成接口：一套请求体、一个 `model` 字段即可调用平台全部图片模型，支持文生图（text-to-image）与图生图/图片编辑（image-to-image），支持多参考图、多种宽高比与多分辨率档（1K/2K/4K）输出。

接口为**异步任务**协议：创建任务后立即返回 `taskId`，随后通过查询接口轮询结果，或配置 `callback_url` 由平台在任务完成时主动回调。

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

> 兼容说明：本接口与主流图片生成服务的 `/v1/images/generations` 路径保持一致，从其它平台迁移时通常只需替换 Base URL 与鉴权 Token。

---

## 认证方式

所有接口均需在请求头中携带 Token 进行认证：

```
Authorization: Bearer {YOUR_AUTH_TOKEN}
```

---

## 快速开始

### 创建文生图任务

```bash
curl -X POST "https://api.apiverse.ai/v1/images/generations" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A surreal painting of a giant banana floating in space",
    "size": "16:9",
    "quality": "high"
  }'
```

### 创建图生图任务（多参考图）

```bash
curl -X POST "https://api.apiverse.ai/v1/images/generations" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "融合这些图片的风格，生成一张新的艺术作品",
    "image": [
      "https://example.com/ref1.jpg",
      "https://example.com/ref2.jpg"
    ],
    "size": "1:1",
    "quality": "high"
  }'
```

### 查询任务状态

```bash
curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/task_20260509150000_abc12345" \
  -H "Authorization: Bearer your_auth_token_here"
```

---

## 接口列表

### 1. 创建图片生成任务

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

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

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| model | string | 是 | 模型标识，决定使用哪个图片模型，见下方「支持的模型」 |
| prompt | string | 是 | 图片描述提示词 |
| image | string[] | 否 | 参考图片列表（URL 或 base64 data URI）；传入即进入图生图/编辑模式。各模型支持的最大张数不同，见下方「支持的模型」 |
| size | string | 否 | 宽高比或分辨率档。含冒号时按宽高比解析（如 `16:9`、`1:1`）；为 `1K`/`2K`/`4K` 时按分辨率档解析；也支持 `1792x1024` 这类像素串，平台会就近映射到标准比例。默认值随模型而定 |
| quality | string | 否 | 质量档，`high` 表示更高分辨率输出；具体档位随模型而定，见下方「支持的模型」。显式传了 `resolution` 时以 `resolution` 为准 |
| resolution | string | 否 | 分辨率档 `1k` / `2k` / `4k`，优先级高于 `size` 里的档位与 `quality`。GPT Image 2 系列支持 1K/2K/4K，`seedream-5.0-pro` 支持 1K/2K |
| nsfw_check | boolean | 否 | 安全审核开关。GPT Image 2 系列支持；与 `extra_body.nsfw_checker` 同时存在时以本字段为准 |
| mask | string | 否 | 蒙版图（URL 或 base64 data URI），用于局部编辑。仅部分模型支持（如 `gpt-image-2`） |
| n | integer | 否 | 生成数量，默认 `1`；部分模型固定单张输出，超出上限会自动收敛 |
| image_urls / mask_url | mixed | 否 | `image` / `mask` 的兼容别名，二选一，不可与本名同传 |
| background / moderation / output_format / output_compression / user | mixed | 否 | `gpt-image-2-official` 的 OpenAI 图片参数，详见该模型专属文档 |
| extra_body | object | 否 | 模型私有参数，按模型解析，见下方「模型私有参数」 |
| callback_url | string | 否 | 任务完成后的回调通知 URL |
| task_nickname | string | 否 | 任务昵称，便于业务侧标记 |

> **说明：**
> - `size` 一个字段承载「宽高比」与「分辨率档」两种含义：需要指定画面比例时传 `16:9` 这类比例串，需要指定清晰度时传 `1K`/`2K`/`4K`。若两者都要控制，GPT Image 2 系列可用比例串作 `size` + `resolution` 显式指定档位（推荐），其它模型可用 `high` 作 `quality` 升清晰度，或通过 `extra_body` 传模型私有的分辨率字段（见下）。
> - 分辨率档优先级：`resolution` > `size` 里的档位串 > `quality`。例如 `size=16:9` + `resolution=4k` 得到 16:9 的 4K 图。
> - 传入 `image` 后即为图生图/编辑模式，模型将基于参考图片进行生成。
> - `image` 与 `mask` 均支持公网 URL 或完整 base64 data URI（如 `data:image/jpeg;base64,...`）。

#### 请求示例

**基础文生图：**
```json
{
  "model": "gpt-image-2",
  "prompt": "A surreal painting of a giant banana floating in space"
}
```

**指定分辨率与尺寸：**
```json
{
  "model": "nano-banana-2",
  "prompt": "一只可爱的猫咪坐在窗台上，阳光洒落，超写实风格",
  "size": "16:9",
  "quality": "high"
}
```

**图生图编辑（单张参考图）：**
```json
{
  "model": "gpt-image-2",
  "prompt": "将图片转换为水彩画风格，保持构图不变",
  "image": ["https://example.com/input.jpg"],
  "size": "1:1"
}
```

**局部编辑（带蒙版）：**
```json
{
  "model": "gpt-image-2",
  "prompt": "把蒙版区域替换为一片花海",
  "image": ["https://example.com/input.jpg"],
  "mask": "https://example.com/mask.png"
}
```

**带回调地址：**
```json
{
  "model": "seedream-5.0-pro",
  "prompt": "星空下的古老城堡，油画风格",
  "size": "21:9",
  "quality": "high",
  "callback_url": "https://your-server.com/callback"
}
```

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| 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"
  }
}
```

---

### 2. 查询任务状态

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

查询单个任务的执行状态。任务处于 `processing` 时请按「最佳实践」中的策略轮询，直到 `success` 或 `failed`。

#### 响应参数

| 参数 | 类型 | 说明 |
|-----|------|------|
| code | int | 状态码，0 表示成功 |
| msg | string | 状态信息 |
| data.taskId | string | 任务 ID |
| data.status | string | 任务状态：`processing` / `success` / `failed` |
| data.result | string[] | 生成结果图片 URL 列表（成功时返回） |
| data.progress | int | 进度 0-100 |
| data.pointConsume | string | 实际消费 |
| data.errorCode | string | 错误码（失败时返回） |
| data.errorMsg | string | 错误信息（失败时返回） |
| data.createdAt | string | 创建时间 |
| data.updatedAt | string | 更新时间 |

#### 响应示例

**成功**
```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"
  }
}
```

**处理中**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260509150000_abc12345",
    "status": "processing",
    "progress": 30,
    "createdAt": "2026-05-09 15:00:00",
    "updatedAt": "2026-05-09 15:00:08"
  }
}
```

---

## 支持的模型

`model` 字段取值及各模型的参数差异如下。带别名的模型任填其一即可。

| model 取值（别名） | 说明 | 参考图最大张数 | quality 档位 |
|---|---|---|---|
| `gpt-image-2` | GPT Image 2 | 不限（按提示词与算力实际处理） | `high` 升 2K，其余 1K；也可用 `resolution` 显式指定 1K/2K/4K（优先级高于 `quality`） |
| `gpt-image-2-official` | OpenAI 官方 GPT Image 2，按 token 计费，支持文生图、图生图、蒙版编辑及 1–4 张 PNG/JPEG 输出。另有模型专属入口 `POST /api/v2/open/aigc/gpt-image-2-official` | 最多 16 张 | `auto` / `low` / `medium` / `high` |
| `gpt-image-2-pro` | GPT Image 2 Pro | 不限 | `high` 升 2K，其余 1K；也可用 `resolution` 显式指定 1K/2K/4K（优先级高于 `quality`） |
| `nano-banana` | Nano Banana | 10 | `high` 升清晰度 |
| `nano-banana-2` | Nano Banana 2 | 14 | `high` 升清晰度 |
| `nano-banana-2-lite` | Nano Banana 2 Lite | 10 | `high` 升清晰度 |
| `nano-banana-pro` | Nano Banana Pro | 8 | `high` 升清晰度 |
| `seedream-4.5` | Seedream 4.5 | 14 | `basic`(2K) / `high`(4K) |
| `seedream-5.0-lite` | Seedream 5.0 Lite | 14 | `basic`(3K) / `high`(4K) |
| `seedream-5.0-pro` | Seedream 5.0 Pro | 10 | `basic`(1K) / `high`(2K) |
| `qwen-image-3`（`qwen-image-3.0`） | Qwen Image 3 | 不限 | `high` 升 2K，其余 1K（无 4K） |
| `qwen-image-3-pro`（`qwen-image-3.0-pro`） | Qwen Image 3 Pro | 不限 | 同上（无 4K） |
| `grok-imagine-1.5` | Grok Imagine 1.5 | 1（多传仅取首张） | — |

> **说明：**
> - Seedream 系列的 `quality` 仅接受 `basic` / `high` 两个值，传其它值会返回参数错误；其余模型的 `quality` 除 `high` 外按普通清晰度处理。
> - `nano-banana-2` / `nano-banana-2-lite` / `qwen-image` 系列 / Seedream 系列单次请求固定输出 1 张，`n` 传入无效。
> - 未列出的图片模型（如按业务动态开通的模型）同样通过本接口的 `model` 字段调用，取值以平台开通清单为准。

### 模型私有参数（extra_body）

部分模型支持通过 `extra_body` 传入私有参数：

| model | extra_body 字段 | 说明 |
|---|---|---|
| `gpt-image-2` / `gpt-image-2-pro` | `nsfw_checker`(bool) | 是否开启内容审核；等价于顶层 `nsfw_check`，两者同传时以顶层为准 |
| `grok-imagine-1.5` | `nsfw_checker`(bool) | 是否开启内容审核 |
| `nano-banana` | `output_format`(png/jpeg) | 输出格式，默认 png |
| `nano-banana-2` | `output_format`(jpg/png) | 输出格式，默认 jpg |
| `nano-banana-pro` | `output_format`(png/jpg)、`aspect_ratio`、`resolution`(1K/2K/4K) | 优先级高于通用 `size`/`quality` |
| `seedream-4.5` / `seedream-5.0-lite` | `nsfw_checker`(bool) | 是否开启内容审核 |
| `seedream-5.0-pro` | `nsfw_checker`(bool)、`genType`(t2i/i2i，可带 `-layer` 后缀)、`layerDecomposition`(bool) | 图层分解需至少提供一张输入图 |
| `qwen-image-3-pro` | `promptExtendMode`(direct/agent) | `agent` 仅支持文生图 |

示例（开启内容审核）：
```json
{
  "model": "gpt-image-2",
  "prompt": "a cat",
  "extra_body": { "nsfw_checker": true }
}
```

---

## 回调通知

当任务完成（成功或失败）时，若创建任务时提供了 `callback_url`，平台会向该 URL 发送 POST 请求。

### 回调请求

**Headers**
```
Content-Type: application/json
X-Funcloud-Event: task.completed
X-Funcloud-Signature: {签名}
```

**Body**
```json
{
  "event": "task.completed",
  "timestamp": "2026-05-09T15:00:25+08:00",
  "signature": "a1b2c3d4e5f6...",
  "data": {
    "taskId": "task_20260509150000_abc12345",
    "status": "success",
    "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/output_001.png"],
    "progress": 100,
    "createdAt": "2026-05-09 15:00:00",
    "updatedAt": "2026-05-09 15:00:25"
  }
}
```

> - `data` 字段结构与查询接口返回的 `data` 一致。
> - `X-Funcloud-Signature` 为 HMAC-SHA256 签名，可用于校验回调来源，签名值同时出现在 Header 与 Body 的 `signature` 字段。
> - 回调失败会按 5s / 30s / 180s 的间隔重试。

---

## 错误码

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

---

## 最佳实践

### 1. 轮询策略

建议的轮询间隔：
- 前 30 秒：每 3 秒查询一次
- 30 秒后：每 5 秒查询一次

### 2. 使用回调

生产环境建议使用 `callback_url` 回调通知而非轮询，可显著降低查询请求量。

### 3. 处理时间参考

- 文生图（1K）：通常 5 ~ 20 秒
- 文生图（2K/4K）：通常 10 ~ 30 秒
- 图生图编辑：通常 10 ~ 30 秒

### 4. 分辨率选择

| 分辨率 | 适用场景 |
|--------|---------|
| 1K | 快速预览、社交媒体 |
| 2K | 高质量展示、网页素材 |
| 4K | 印刷品、大尺寸海报 |

### 5. 结果时效

生成的图片 URL 请及时下载保存，避免长期依赖临时链接。