# Seedream 5.0 Pro 图片生成 API 对接文档（海外加白） ## 概述 Seedream 5.0 Pro 图片生成接口，支持文生图（text-to-image）和图生图（image-to-image）两种模式。 **Base URL**: `https://api.apiverse.ai` > 本文档为海外加白版本。 --- ## 认证方式 所有接口均需要在请求头中携带 Token 进行认证： ``` Authorization: Bearer {YOUR_AUTH_TOKEN} ``` ## 快速开始 ### cURL 示例 **创建文生图任务** ```bash curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/seedream-5.0-pro" \ -H "Authorization: Bearer your_auth_token_here" \ -H "Content-Type: application/json" \ -d '{ "prompt": "一只可爱的猫咪坐在窗台上，阳光洒落", "genType": "t2i", "aspectRatio": "16:9", "resolution": "2K" }' ``` **创建图生图任务** ```bash curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/seedream-5.0-pro" \ -H "Authorization: Bearer your_auth_token_here" \ -H "Content-Type: application/json" \ -d '{ "prompt": "将图片转换为水彩画风格", "genType": "i2i", "imageUrls": ["https://example.com/reference.jpg"], "aspectRatio": "1:1", "resolution": "1K" }' ``` **查询任务状态** ```bash curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/task_abc123" \ -H "Authorization: Bearer your_auth_token_here" ``` --- ## 接口列表 ### 1. 创建 Seedream 5.0 Pro 图片生成任务 **POST** `/api/v2/open/aigc/seedream-5.0-pro` 创建一个 Seedream 5.0 Pro 图片生成任务。 **Content-Type**: `application/json` #### 请求参数 | 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | prompt | string | 条件 | 图片描述提示词，非图层拆分时必填；图层拆分时可省略 | | genType | string | 否 | 生成类型：`t2i`(文生图,默认) / `i2i`(图生图) / `t2i-layer`(图层拆分) / `i2i-layer`(图生图层拆分) | | imageUrls | string[] | 条件 | 参考图片 URL（i2i/layer时必填，最多10张，JPEG/PNG/WebP，每张最大10MB） | | aspectRatio | string | 否 | 宽高比：`auto` / `1:1`(默认) / `4:3` / `3:4` / `16:9` / `9:16` / `2:3` / `3:2` / `21:9` | | resolution | string | 否 | 输出分辨率：`1K`(默认) / `2K` | | size | string | 否 | 兼容字段：可传宽高比，也可直接传 `1K` / `2K` | | quality | string | 否 | 兼容旧字段：`basic`(1K) / `high`(2K) | | nsfwChecker | boolean | 否 | 内容过滤开关，设为false时禁用内容过滤，默认false | | callbackUrl | string | 否 | 任务完成后的回调通知 URL | > **说明**： > - 图生图(i2i)时必须提供 imageUrls > - `auto` 在网关侧解析：文生图按 `1:1`，图生图按首张参考图的最近合法比例 > - 分辨率优先级：`resolution` > `size` 中的 `1K`/`2K` > `quality` > - 图层拆分(`t2i-layer` / `i2i-layer`)时必须提供 1 张输入图，输出为透明 PNG 图层（底图 + 若干透明图层） > - 图层拆分时 prompt 可选：留空则自动识别主要元素；也可通过 `x1 y1 x2 y2` 归一化坐标（取值 0-1000）指定要分离的元素 > - 创建任务时会预扣费，余额不足将返回错误 #### 请求示例 **文生图（1K质量）：** ```json { "prompt": "一只可爱的猫咪坐在窗台上，阳光洒落", "aspectRatio": "16:9", "resolution": "1K" } ``` **文生图（2K质量）：** ```json { "prompt": "星空下的古老城堡，超写实风格", "genType": "t2i", "aspectRatio": "16:9", "resolution": "2K" } ``` **图生图：** ```json { "prompt": "将图片转换为水彩画风格，保持构图不变", "genType": "i2i", "imageUrls": ["https://example.com/input.jpg"], "aspectRatio": "1:1", "resolution": "1K" } ``` #### 响应参数 | 参数 | 类型 | 说明 | |-----|------|------| | code | int | 状态码，0 表示成功 | | msg | string | 状态信息 | | data.taskId | string | 任务 ID，用于查询任务状态 | | data.status | string | 任务状态，创建时固定为 `processing` | | data.createdAt | string | 创建时间 | #### 响应示例 **成功** ```json { "code": 0, "msg": "success", "data": { "taskId": "task_20260506150000_abc12345", "status": "processing", "createdAt": "2026-05-06 15:00:00" } } ``` **余额不足** ```json { "code": 40001, "msg": "余额不足: 当前余额不足以支付本次任务", "data": null } ``` --- ### 2. 查询任务状态 **GET** `/api/v2/open/aigc/{taskId}` 查询单个任务的执行状态。 #### 响应示例 **成功** ```json { "code": 0, "msg": "success", "data": { "taskId": "task_20260506150000_abc12345", "status": "success", "result": [ "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/06/output_001.png" ], "createdAt": "2026-05-06 15:00:00", "updatedAt": "2026-05-06 15:00:30" } } ``` **图层拆分任务的返回** 当任务为图层拆分（`genType` 为 `t2i-layer` / `i2i-layer`）时，除扁平的 `result` 图片数组外，`data` 下还会额外返回 `seedreamLayerOutput.layers` 字段，给出每个图层的结构化信息。两者并列返回，`result` 与 `layers` 中的图片一一对应（均按 `zIndex` 升序）。 | 字段 | 类型 | 说明 | |-----|------|------| | seedreamLayerOutput.layers | object[] | 图层列表，按 `zIndex` 升序 | | layers[].url | string | 图层图片地址 | | layers[].zIndex | int | 图层层级，`0` 为背景底图，数值越大越靠上 | | layers[].size | string | 图层图片尺寸，如 `2048x2048` | | layers[].outputFormat | string | 图层图片格式，固定 `png` | | layers[].name | string | 图层名称（背景层无此字段） | | layers[].description | string | 图层内容描述（背景层无此字段） | | layers[].boundingBox | object | 该元素在原图中的位置框（背景层无此字段） | | layers[].boundingBox.absolute | int[] | 绝对像素坐标 `[x1, y1, x2, y2]` | | layers[].boundingBox.normalized | int[] | 归一化坐标 `[x1, y1, x2, y2]`（取值 0-1000） | > **说明**：背景层（`zIndex` 为 `0`）为完整底图，不含 `name` / `description` / `boundingBox`；其余前景图层均包含这三个字段。 **图层拆分响应示例（3 层：背景 + 2 前景）** ```json { "code": 0, "msg": "success", "data": { "taskId": "task_20260506150000_abc12345", "status": "success", "result": [ "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/06/layer_0.png", "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/06/layer_1.png", "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/06/layer_2.png" ], "seedreamLayerOutput": { "layers": [ { "url": "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/06/layer_0.png", "zIndex": 0, "size": "2048x2048", "outputFormat": "png" }, { "url": "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/06/layer_1.png", "zIndex": 1, "size": "1137x2139", "outputFormat": "png", "name": "前景主体", "description": "画面中的主体对象，仅保留主体本身", "boundingBox": { "absolute": [731, 627, 1480, 2034], "normalized": [357, 306, 722, 993] } }, { "url": "https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/2026/05/06/layer_2.png", "zIndex": 2, "size": "1806x1773", "outputFormat": "png", "name": "标题文字", "description": "画面中的全部标题文字元素，保留原始文字内容与字体样式", "boundingBox": { "absolute": [139, 120, 1945, 1893], "normalized": [68, 59, 949, 924] } } ] }, "createdAt": "2026-05-06 15:00:00", "updatedAt": "2026-05-06 15:00:30" } } ``` --- ### 3. 批量查询任务状态 **POST** `/api/v2/open/aigc/batch` 批量查询多个任务的执行状态（最多 100 个）。 --- ### 4. 查询账户余额 **GET** `/api/v2/open/balance` --- ## 回调通知 当任务完成（成功或失败）时，如果创建任务时提供了 `callbackUrl`，系统会向该 URL 发送 POST 请求。 ### 回调请求 **Headers** ``` Content-Type: application/json X-Funcloud-Event: task.completed X-Funcloud-Signature: {签名} ``` **Body** ```json { "event": "task.completed", "taskId": "task_20260506150000_abc12345", "status": "success", "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/images/output_001.png"], "errorMsg": "", "timestamp": "2026-05-06T15:00:30+08:00", "signature": "a1b2c3d4e5f6..." } ``` --- ## 错误码 | code | 说明 | |------|------| | 0 | 成功 | | 10002 | 参数缺失或格式错误 | | 10005 | API Key 无效或缺失 | | 30003 | 任务不存在 | | 40001 | 余额不足 | | 90003 | 服务器内部错误 | --- ## 最佳实践 ### 1. 轮询策略 建议的轮询间隔： - 前 30 秒：每 3 秒查询一次 - 30 秒后：每 5 秒查询一次 ### 2. 使用回调 生产环境建议使用回调通知而非轮询。 ### 3. 处理时间参考 - 文生图(basic/1K)：通常 5 ~ 15 秒 - 文生图(high/2K)：通常 10 ~ 30 秒 - 图生图(basic/1K)：通常 5 ~ 15 秒 - 图生图(high/2K)：通常 10 ~ 30 秒 ### 4. 余额管理 - 创建任务前建议先查询余额 - 任务成功后会从冻结余额中扣费 - 任务失败后冻结金额会自动退还到可用余额