接口说明
- 普通生图每次只返回一张图片，不支持组图生成。
- 不支持流式输出和联网搜索工具。
- 图层拆分仅接受一张 PNG 或 JPEG 图片，返回一张底图和最多 16 个可编辑 PNG 图层。
- 结果 URL 由平台托管，仅支持 URL 返回格式。
认证
authorization string 必需
所有 API 均使用 Bearer Token 鉴权
获取 API Key：
访问 API Key 管理页面 获取 API Key
用法：
将以下 Header 添加到请求中：
Authorization: Bearer YOUR_API_KEY参数
model string 必需
请求使用的模型 ID。
值：spark_dream_5_0_pro
prompt string
用于描述要生成的图片，或指定要拆分的图层元素。
普通生图场景必填。图层拆分场景可选；不传时，模型会自动识别输入图片中的主要元素。
建议中文提示词不超过 300 字，英文提示词不超过 600 词。模型还支持俄语、阿拉伯语、菲律宾语、泰语、土耳其语、韩语、马来语、西班牙语、葡萄牙语、印尼语、法语、德语、越南语和日语提示词。
image string | array
输入图片 URL 或 Base64 Data URI，Base64 格式为 data:image/<图片格式>;base64,<内容>。
普通生图场景：
- 不传
image时为文生图。 - 传入一张图片时为单图编辑。
- 传入 2–10 张图片时为多参考图生成。
- 支持
jpeg、png、webp、bmp、tiff、gif、heic、heif。 - 单张图片不超过 30 MB，宽高比范围为
1/16到16，总像素不超过 36,000,000。
图层拆分场景必须且只能传入一张 PNG 或 JPEG 图片。图片不超过 30 MB，宽高比范围为 1/16 到 16，总像素范围为 262,144 到 36,000,000。
layer_decomposition boolean
是否开启图层拆分。
false：普通生图，不拆分图层。true：将输入图片拆分为一张底图和最多 16 个可独立编辑的图层。
默认值：false
每个拆分图层都是带透明通道的 PNG 图片。任一图层生成失败时，整个请求失败，不会返回部分成功结果。
size string
普通生图支持使用分辨率档位或准确的 宽x高 像素值。
- 分辨率档位：
1K、1.5K、2K。 - 默认值：
2K。 - 自定义尺寸的总像素范围为 921,600 到 4,624,220，宽高比范围为
1/16到16。
常用档位对应尺寸：
| 档位 | 1:1 | 4:3 | 3:4 | 16:9 | 9:16 |
|---|---|---|---|---|---|
1K | 1024x1024 | 1152x864 | 864x1152 | 1424x800 | 800x1424 |
1.5K | 1536x1536 | 1792x1344 | 1344x1792 | 2048x1152 | 1152x2048 |
2K | 2048x2048 | 2368x1776 | 1776x2368 | 2816x1584 | 1584x2816 |
图层拆分仅支持 1K、1.5K、2K、auto。默认值为 auto：符合范围时保留原始尺寸，否则在保持宽高比的前提下，将每个结果调整到支持的 1K–2K 范围。
optimize_prompt_options object
提示词优化配置。
mode 支持：
standard：优先保证生成质量。fast：减少生成耗时，效果略低于标准模式。
默认值：standard
output_format string
生成图片或图层拆分底图的文件格式。
可选值：png、jpeg
默认值：jpeg
图层拆分场景下，该参数只控制底图格式，各个图层始终返回 PNG 文件。
background string
控制输出图片是否带透明背景。
opaque：生成普通不透明背景。transparent：生成带透明通道的图片。
默认值：opaque
透明背景仅支持图生图场景，且只能输入一张支持透明通道的图片。此时必须使用 output_format: "png"，JPEG 不支持透明通道。
response_format string
图片返回格式。平台固定返回托管后的图片 URL。
值：url
watermark boolean
是否在图片右下角添加“AI 生成”水印。
默认值：true
图层拆分示例
curl --location 'https://cloud.vtrix.ai/model/v1/generation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
"model": "spark_dream_5_0_pro",
"input": [
{
"params": {
"image": "https://example.com/source-with-alpha.png",
"prompt": "拆分标题、前景产品和背景",
"layer_decomposition": true,
"size": "auto",
"output_format": "png",
"background": "transparent",
"watermark": false
}
}
]
}'轮询
由于结果生成需要时间，您需要在创建任务后轮询任务状态
初始响应只返回任务 ID 和初始状态等信息，最终生成结果需通过使用该任务 ID 轮询任务状态接口获取
轮询请求与响应示例见右侧
响应格式
通用字段
| 字段 | 类型 | 说明 |
|---|---|---|
error | object | 错误信息，仅在 status 为 failed 时出现。 |
output | array | 输出分组，生成图片位于分组的 content 数组中。 |
usage | object | 使用统计，在任务成功完成后出现。 |
metadata | object | 任务耗时和其他元数据。 |
模型返回对应信息时，每个图片项包含 type、url、size 和 output_format。
图层字段
图层拆分会在每个图片项中增加以下字段：
| 字段 | 类型 | 说明 |
|---|---|---|
z_index | integer | 叠放顺序。底图固定为 0，图层从 1 开始，数值越大越靠上。 |
name | string | 模型生成的图层名称。 |
description | string | 模型生成的图层内容描述。 |
bounding_box.absolute | integer[4] | 底图坐标系中的像素坐标 [left, top, right, bottom]，底图不返回该字段。 |
bounding_box.normalized | integer[4] | 归一化到整数区间 [0, 1000] 的相同边界，底图不返回该字段。 |
任务完成响应示例：
{
"id": "d5u5obte8783ap44qtj0",
"created_at": 1788451200000,
"status": "completed",
"model": "spark_dream_5_0_pro",
"output": [
{
"content": [
{
"type": "image",
"url": "https://example.com/base.png",
"size": "2048x2048",
"output_format": "png",
"z_index": 0,
"name": "base",
"description": "Base image"
},
{
"type": "image",
"url": "https://example.com/title.png",
"size": "1024x256",
"output_format": "png",
"z_index": 1,
"name": "title",
"description": "Title layer",
"bounding_box": {
"absolute": [180, 64, 812, 198],
"normalized": [88, 31, 396, 97]
}
}
]
}
],
"usage": {
"input_images": 1,
"generated_images": 2,
"output_tokens": 23107,
"total_tokens": 23107
}
}使用 absolute 坐标还原图层时，将图层缩放为 (right - left) x (bottom - top)，再放置到 (left, top)。组合多个图层时，按 z_index 从小到大依次叠放。
在宽高为 W x H 的自定义画布中，可按以下方式换算 normalized 坐标：
x = left / 1000 * W
y = top / 1000 * H
width = (right - left) / 1000 * W
height = (bottom - top) / 1000 * H