接口提示
spark_dream_5_0_flash 支持文生图、单图编辑和最多 10 张参考图，普通生成每次输出 1 张图片
spark_dream_5_0_flash 的模型参数放在 input[0].params，包装固定返回平台托管的图片 URL，不支持 Base64 输出
spark_dream_5_0_flash 不支持 stream、sequential_image_generation、sequential_image_generation_options、tools 和 optimize_prompt_options.mode: "fast"
spark_dream_5_0_flash 的图层拆分只接受 1 张 PNG 或 JPEG 图片，返回基图和最多 16 个图层
认证
authorization string 必需
所有 API 均使用 Bearer Token 鉴权
获取 API Key：
访问 API Key 管理页面 获取 API Key
用法：
将以下 Header 添加到请求中：
Authorization: Bearer YOUR_API_KEY参数
model string 必需
请求使用的客户模型 ID
值: spark_dream_5_0_flash
input array 必需
传入一个包含 params 的对象，以下模型参数均位于 input[0].params
prompt string
普通生成和参考图编辑时必填；拆层时可选，不传则自动识别主要元素
建议中文不超过 300 字、英文不超过 600 词
image string | array
输入可访问的图片 URL 或 Base64 Data URI，格式为 data:image/<format>;base64,<content>，格式名使用小写
不传时为文生图；单张图片用于编辑，2 至 10 张图片用于多参考图生成
普通输入支持 jpeg、png、webp、bmp、tiff、gif、heic、heif；每张不超过 30 MB，宽和高均大于 14 像素，总像素不超过 36,000,000，宽高比为 1/16 至 16
拆层必须且只能传入一张 PNG 或 JPEG，总像素为 262,144 至 36,000,000，文件大小及宽高比限制相同
layer_decomposition boolean
启用时返回一张基图和最多 16 个独立图层，图层均为带透明通道的 PNG
任一图层生成失败时整个请求失败，不返回部分成功结果；请求超过上限的图层数量可能丢失部分元素
默认值: false
size string
普通生成可指定档位，或使用 宽x高 像素值；自定义尺寸须同时满足总像素 921,600 至 4,624,220、宽高比 1/16 至 16
拆层仅支持档位或 auto，不支持自定义宽高；基图保持原图宽高比，各图层保持对应区域的宽高比
auto 分别处理基图和各图层：总像素在上述范围内保留原尺寸，小于范围时调整到 1K，大于范围时调整到 2K
普通生成可选值: 1K、1.5K、2K 或合法宽高
普通生成默认值: 2K
拆层可选值: 1K、1.5K、2K、auto
拆层默认值: auto
常见档位尺寸参考：
| 档位 | 1:1 | 4:3 | 3:4 | 16:9 | 9:16 | 3:2 | 2:3 | 21:9 |
|---|---|---|---|---|---|---|---|---|
1K | 1024x1024 | 1152x864 | 864x1152 | 1424x800 | 800x1424 | 1248x832 | 832x1248 | 1568x672 |
1.5K | 1536x1536 | 1792x1344 | 1344x1792 | 2048x1152 | 1152x2048 | 1872x1248 | 1248x1872 | 2352x1008 |
2K | 2048x2048 | 2368x1776 | 1776x2368 | 2816x1584 | 1584x2816 | 2496x1664 | 1664x2496 | 3136x1344 |
optimize_prompt_options object
提示词优化配置
mode
string使用标准提示词优化，不支持
fast可选值:
standard
默认值:standard
output_format string
普通生成的输出格式；拆层时仅控制基图格式，各图层始终为 PNG
可选值: png、jpeg
默认值: jpeg
background string
控制输出图片是否带透明背景
透明背景编辑仅支持一张带 Alpha 通道的输入图片，应明确设置 output_format: "png"；JPEG 输入或输出不满足该条件
透明背景模式未指定输出格式时使用 PNG；普通 PNG 或 JPEG 拆层不需要设置 background: "transparent"
可选值: opaque、transparent
默认值: opaque
response_format string
包装固定返回平台托管的图片 URL，传入其他格式不会启用 Base64 输出
值: url
watermark boolean
是否在图片右下角添加 AI 生成水印
默认值: true
请求示例
右侧文生图示例使用 POST /model/v1/generation。以下参考图 URL 为占位地址，调用前须替换为可访问的实际图片
参考图编辑
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_flash",
"input": [{"params": {
"prompt": "Change the background to pale green and keep the main subject",
"image": "https://example.com/reference.png",
"size": "1K",
"output_format": "png",
"watermark": false
}}]
}'图层拆分
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_flash",
"input": [{"params": {
"image": "https://example.com/source.png",
"prompt": "Separate the title, foreground subject, and background",
"layer_decomposition": true,
"size": "auto",
"output_format": "png",
"watermark": false
}}]
}'同步调用
同步接口使用相同请求体，等待任务完成后返回结果；客户端应为生成过程设置足够的请求超时
curl --location 'https://cloud.vtrix.ai/model/v1/generation/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
"model": "spark_dream_5_0_flash",
"input": [{"params": {
"prompt": "A red circle on a white background",
"size": "1K",
"output_format": "png",
"watermark": false
}}]
}'轮询
由于结果生成需要时间，您需要在创建任务后轮询任务状态
初始响应只返回任务 ID 和初始状态等信息，最终生成结果需通过使用该任务 ID 轮询任务状态接口获取
轮询请求与响应示例见右侧
异步创建响应中的 status: "completed" 表示创建请求完成，不代表图片已生成。使用返回的 id 替换查询 URL 中的 task_id，查询到 completed 且包含 output 后读取结果
| 任务查询状态 | 含义 |
|---|---|
in_progress | 继续查询同一个任务 |
completed | 读取 output[].content[] |
failed | 读取 error.code、error.message |
响应格式
图片与用量
| 字段 | 类型 | 说明 |
|---|---|---|
output[].content[].type | string | image |
output[].content[].url | string | 平台托管的图片 URL |
output[].content[].size | string | 返回时表示实际宽高，如 1024x1024 |
output[].content[].output_format | string | 返回时表示 png 或 jpeg |
usage.input_images | number | 输入图片数量，返回时可读取 |
usage.generated_images | number | 成功输出图片总数，拆层包含基图和全部图层 |
usage.quantity | number | 计费数量 |
usage.cost | string | 本次费用，单位 USD |
metadata | object | 任务耗时等元数据，返回时可读取 |
图层字段
| 字段 | 类型 | 说明 |
|---|---|---|
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] 的相同边界，基图不含此字段 |
以下为基图加一层的示意响应，仅展示相关字段，URL 为占位地址：
{
"id": "task_id",
"status": "completed",
"model": "spark_dream_5_0_flash",
"output": [{"content": [
{
"type": "image",
"url": "https://example.com/base.png",
"size": "1024x1024",
"output_format": "png",
"z_index": 0,
"name": "base",
"description": "Base image"
},
{
"type": "image",
"url": "https://example.com/title.png",
"size": "2048x512",
"output_format": "png",
"z_index": 1,
"name": "title",
"description": "Title layer",
"bounding_box": {
"absolute": [128, 64, 896, 256],
"normalized": [125, 63, 875, 250]
}
}
]}],
"usage": {
"input_images": 1,
"generated_images": 2,
"quantity": 2,
"cost": "0.036"
}
}还原时，将图层缩放为 (right - left) x (bottom - top) 并放在 (left, top)，按 z_index 从小到大叠放
自定义 W x H 画布中，归一化坐标按横坐标乘 W / 1000、纵坐标乘 H / 1000 换算
价格
基准价为 0.018 USD/成功输出张，输入图免费，尺寸不影响该基准价。实际费用以适用折扣和终态 usage.cost 为准
| 场景 | 成功输出数量 | 基准费用 |
|---|---|---|
| 普通生成或编辑 | 1 张 | 0.018 USD |
基图加 7 个图层 | 8 张 | 0.144 USD |
失败且没有成功输出的请求不收取图片生成费用。拆层中的基图及各图层均计入输出数量
当前拆层响应的 usage.unit_price 是兼容合计字段，不应作为每张单价再乘输出数量。费用应读取 usage.cost，输出数量读取 usage.generated_images
错误处理
任务失败时读取 error.code 和 error.message。请检查提示词、图片可访问性、图片类型及尺寸、透明背景条件和拆层输入数量；包装错误不保证保留底层接口的具体错误码