Spark Dream 4.0

认证

authorization `string` 必需

所有 API 均使用 Bearer Token 鉴权

获取 API Key：

用法：

将以下 Header 添加到请求中：

Authorization: Bearer YOUR_API_KEY

参数

model `string` 必需

请求使用的模型 ID

值: spark_dream_4_0

prompt `string` 必需

用于生成图像的提示词, 支持中英文

建议不超过 300 个汉字或 600 个英文单词. 字数过多信息容易分散, 模型可能因此忽略细节, 只关注重点, 造成图片缺失部分元素

image `string` | `array`

输入的图片信息, 支持 URL 或 Base64 编码, 支持单图或多图输入

图片 URL：请确保图片 URL 可被访问
Base64 编码：请遵循此格式 data:image/<图片格式>;base64,<Base64编码>. 注意 <图片格式> 需小写, 如 data:image/png;base64,<base64_image>

传入图片需要满足以下条件：
图片格式：JPEG, PNG, WebP, BMP, TIFF, GIF
宽高比（宽/高）范围：1/16 到 16
宽高长度（px）> 14
大小：不超过 10MB
总像素：不超过 6000x6000=36000000 px（对单张图宽度和高度的像素乘积限制, 而不是对宽度或高度的单独值进行限制）
最多支持传入 14 张参考图

size `string`

指定生成图像的尺寸信息. 支持以下两种方式, 不可混用

方式 1：指定生成图像的分辨率, 并在 prompt 中用自然语言描述图片宽高比、图片形状或图片用途, 最终由模型判断生成图片的大小
可选值：1K, 2K, 4K

方式 2：指定生成图像的宽高像素值
总像素取值范围：1280x720=921600 到 4096x4096=16777216
宽高比取值范围：1/16 到 16

采用方式 2 时, 需同时满足总像素取值范围和宽高比取值范围. 其中, 总像素是对单张图宽度和高度的像素乘积限制, 而不是对宽度或高度的单独值进行限制

有效示例：1600x600
总像素值 1600x600=960000, 符合 [921600, 16777216] 的区间要求；宽高比 1600/600=8/3, 符合 [1/16, 16] 的区间要求, 故该示例值有效

无效示例：800x800
总像素值 800x800=640000, 未达到 921600 的最低要求；宽高 800/800=1, 虽符合 [1/16, 16] 的区间要求, 但因其未同时满足两项限制, 故该示例值无效

推荐的宽高像素值：
1:1: 2048x2048
4:3: 2304x1728
3:4: 1728x2304
16:9: 2560x1440
9:16: 1440x2560
3:2: 2496x1664
2:3: 1664x2496
21:9: 3024x1296

默认值: 2048x2048

sequential_image_generation `string`

控制是否关闭组图功能

组图：基于您输入的内容, 生成的一组内容关联的图片

auto: 自动判断模式, 模型会根据用户提供的提示词自主判断是否返回组图以及组图包含的图片数量
disabled: 关闭组图功能, 模型只会生成一张图

可选值: auto, disabled

默认值: disabled

sequential_image_generation_options `object`

组图功能的配置. 仅当 sequential_image_generation 为 auto 时生效

max_images integer

指定本次请求, 最多可生成的图片数量

实际可生成的图片数量, 除受到 max_images 影响外, 还受到输入的参考图数量影响. 输入的参考图数量 + 最终生成的图片数量 ≤ 15 张

范围: 1 到 15

默认值: 15

stream `boolean`

控制是否开启流式输出模式

false: 非流式输出模式, 等待所有图片全部生成结束后再一次性返回所有信息
true: 流式输出模式, 即时返回每张图片输出的结果. 在生成单图和组图的场景下, 流式输出模式均生效

可选值: true, false

默认值: false

response_format `string`

指定生成图像的返回格式

生成的图片为 JPEG 格式, 支持以下两种返回方式：

url: 返回图片下载链接；链接在图片生成后 24 小时内有效, 请及时下载图片
b64_json: 以 Base64 编码字符串的 JSON 格式返回图像数据

可选值: url, b64_json

默认值: url

watermark `boolean`

是否在生成的图片中添加水印

false: 不添加水印
true: 在图片右下角添加”AI生成”字样的水印标识

可选值: true, false

默认值: true

optimize_prompt_options `object`

提示词优化功能的配置

mode string

设置提示词优化功能使用的模式

standard: 标准模式, 生成内容的质量更高, 耗时较长
fast: 快速模式, 生成内容的耗时更短, 质量一般

可选值: standard, fast

默认值: standard

轮询

由于图像生成需要时间, 您需要在创建任务后轮询任务状态

初始响应返回任务 ID 和初始状态. 实际的生成结果必须通过轮询任务状态端点来获取

响应格式

error `object`

错误信息. 仅在状态为 failed 时出现

code string

错误码

error_message string

详细错误信息

output `array`

生成结果. 仅在状态为 completed 时出现

content array

生成内容列表

type string

资源类型

值: image

url string

生成内容的 URL

usage `object`

使用统计. 仅在状态为 completed 时出现

cost string

总费用（美元）

discount number

折扣金额

metadata `object`

元数据信息

错误码

错误码	描述
003012001	缺少模型
003012002	缺少提示词
003012003	提示词长度无效
003012004	图像格式无效
003012005	图像尺寸无效
003012007	连续生成模式无效
003012009	响应格式无效
003012010	图像数量过多
003012011	尺寸参数无效
003012012	提示词优化模式无效
003012095	内部生成错误
003012096	结果解析异常
003012097	HTTP 错误响应
003012099	服务不可用

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "spark_dream_4_0", "input": [ { "params": { "prompt": "保持模特姿势和液态服装的流动形状不变。将服装材质从银色金属改为完全透明的清水（或玻璃）。透过液态水流，可以看到模特的皮肤细节。光影从反射变为折射。", "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png", "size": "2K", "watermark": false } } ] }'

{ "id": "d5u5obte8783ap44qtj0", "created_at": 1769757744021, "status": "completed", "model": "spark_dream_4_0", "output": [ { "content": [ { "type": "image", "url": "https://example.com/generated-image.jpg" } ] } ], "usage": { "cost": "0.000500", "discount": 0, "input_tokens": null, "output_tokens": null, "quantity": 1, "time_per_unit": 0, "total_tokens": null, "unit_price": "0.000500", "user_discount": 1 }, "metadata": { "completed_at": 120.5, "in_queue_at": 0, "upload_at": 1.2, "usage": { "input_tokens": 20, "input_tokens_details": { "text_tokens": 20 }, "output_tokens": 0, "total_tokens": 20 } } }

认证

authorization `string` 必需

参数

model `string` 必需

prompt `string` 必需

image `string` | `array`

size `string`

sequential_image_generation `string`

sequential_image_generation_options `object`

max_images `integer`

stream `boolean`

response_format `string`

watermark `boolean`

optimize_prompt_options `object`

mode `string`

轮询

响应格式

error `object`

code `string`

error_message `string`

output `array`

content `array`

type `string`

url `string`

usage `object`

cost `string`

discount `number`

metadata `object`

错误码

认证

authorization string 必需

参数

model string 必需

prompt string 必需

image string | array

size string

sequential_image_generation string

sequential_image_generation_options object

max_images integer

stream boolean

response_format string

watermark boolean

optimize_prompt_options object

mode string

轮询

响应格式

error object

code string

error_message string

output array

content array

type string

url string

usage object

cost string

discount number

metadata object

错误码

authorization `string` 必需

model `string` 必需

prompt `string` 必需

image `string` | `array`

size `string`

sequential_image_generation `string`

sequential_image_generation_options `object`

max_images `integer`

stream `boolean`

response_format `string`

watermark `boolean`

optimize_prompt_options `object`

mode `string`

error `object`

code `string`

error_message `string`

output `array`

content `array`

type `string`

url `string`

usage `object`

cost `string`

discount `number`

metadata `object`