图片生成 API（统一入口）对接文档 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}

快速开始

创建文生图任务

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"
  }'

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

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"
  }'

查询任务状态

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,...）。

请求示例

基础文生图：

{
  "model": "gpt-image-2",
  "prompt": "A surreal painting of a giant banana floating in space"
}

指定分辨率与尺寸：

{
  "model": "nano-banana-2",
  "prompt": "一只可爱的猫咪坐在窗台上，阳光洒落，超写实风格",
  "size": "16:9",
  "quality": "high"
}

图生图编辑（单张参考图）：

{
  "model": "gpt-image-2",
  "prompt": "将图片转换为水彩画风格，保持构图不变",
  "image": ["https://example.com/input.jpg"],
  "size": "1:1"
}

局部编辑（带蒙版）：

{
  "model": "gpt-image-2",
  "prompt": "把蒙版区域替换为一片花海",
  "image": ["https://example.com/input.jpg"],
  "mask": "https://example.com/mask.png"
}

带回调地址：

{
  "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	创建时间

响应示例

成功

{
  "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	更新时间

响应示例

成功

{
  "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"
  }
}

处理中

{
  "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` 仅支持文生图

示例（开启内容审核）：

{
  "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

{
  "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 请及时下载保存，避免长期依赖临时链接。