API 接入
火山方舟生图协议
POST https://api.easyx.ai/api/v3/images/generations
Authorization: Bearer easyx_ws_xxx
Content-Type: application/json请求示例
文生图
curl https://api.easyx.ai/api/v3/images/generations \
-H "Authorization: Bearer easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5-0-pro",
"prompt": "一只戴红帽子的柴犬,水彩画风。",
"size": "2K",
"watermark": false
}'单张参考图
curl https://api.easyx.ai/api/v3/images/generations \
-H "Authorization: Bearer easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5-0-pro",
"prompt": "给图中的柴犬戴上蓝帽子。",
"image": "https://example.com/input.png"
}'多张参考图
curl https://api.easyx.ai/api/v3/images/generations \
-H "Authorization: Bearer easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5-0-pro",
"prompt": "将图一的商品放到图二的背景中。",
"image": [
"https://example.com/product.png",
"https://example.com/background.png"
]
}'image 支持单个图片 URL / data URL,也可传参考图数组。将示例 URL 替换为可访问的图片地址。base64 输入使用 data:image/png;base64,BASE64_IMAGE 格式。图片格式、张数和尺寸限制随模型而不同。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 生图模型名称。 |
prompt | string | 是 | 图片描述或修改指令。 |
image | string / array | 否 | 参考图 URL 或 data URL;单图传字符串,多图传数组。 |
size | string | 否 | 像素尺寸(如 1024x1024)或模型支持的分辨率档位(如 2K)。 |
response_format | string | 否 | 支持该参数的模型可选 url 或 b64_json;部分模型固定返回 base64。 |
output_format | string | 否 | 支持该参数的模型可选 jpeg 或 png。 |
watermark | boolean | 否 | 是否添加水印,true 为添加,false 为关闭。 |
seed | integer | 否 | 随机种子,仅支持该参数的模型生效。 |
guidance_scale | number | 否 | 提示词引导强度,仅支持该参数的模型生效。 |
sequential_image_generation | string | 否 | 支持组图的模型可设 auto 或 disabled。 |
sequential_image_generation_options.max_images | integer | 否 | 组图数量上限,需要模型支持。 |
stream | boolean | 否 | 支持流式的模型可设 true 接收 SSE 事件。 |
optimize_prompt_options | object | 否 | 提示词优化选项,支持情况由模型决定。 |
tools | array | 否 | 模型支持的工具配置,例如 web_search。 |
响应
{
"model": "doubao-seedream-5-0-pro",
"created": 1741569952,
"data": [
{
"b64_json": "BASE64_IMAGE",
"size": "2048x2048"
}
],
"usage": {
"generated_images": 1,
"output_tokens": 100,
"total_tokens": 100
}
}{
"model": "doubao-seedream-5-0-pro",
"created": 1741569952,
"data": [
{
"url": "https://example.com/generated-image.jpeg",
"size": "2048x2048"
}
]
}| 字段 | 类型 | 说明 |
|---|---|---|
model | string | 响应中的模型名称。 |
created | integer | 生成时间戳。 |
data | array | 图片结果列表。 |
data[].url | string | 返回 URL 时的图片地址。 |
data[].b64_json | string | 返回 base64 时的图片内容。 |
data[].size | string | 返回时表示实际图片尺寸。 |
usage | object | 模型返回的使用量统计,可能不提供。 |
usage.generated_images | integer | 生成图片数量。 |
usage.output_tokens / total_tokens | integer | 模型返回的 token 统计。 |
error | object | 返回时包含 code 和 message。 |
读取图片结果
import base64
from pathlib import Path
# response is the parsed JSON response
for index, image in enumerate(response["data"]):
if image.get("b64_json"):
Path(f"image-{index}").write_bytes(base64.b64decode(image["b64_json"]))
elif image.get("url"):
print(image["url"])流式生图
支持流式的模型可以传 stream=true。处理以下事件,其中 image_generation.completed 表示本次请求结束。
curl -N https://api.easyx.ai/api/v3/images/generations \
-H "Authorization: Bearer easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-4-5-251128",
"prompt": "一组四季风景。",
"stream": true
}'| 事件 | 说明 |
|---|---|
| image_generation.partial_succeeded | 一张图片生成成功,读取 image_index 与 url 或 b64_json。 |
| image_generation.partial_failed | 一张图片生成失败,检查 error。 |
| image_generation.completed | 本次生成结束,检查最终 usage 与错误。 |
Python
pip install requestsimport requests
response = requests.post(
"https://api.easyx.ai/api/v3/images/generations",
headers={"Authorization": "Bearer easyx_ws_xxx"},
json={
"model": "doubao-seedream-5-0-pro",
"prompt": "A dog wearing a red hat",
},
timeout=600,
)
response.raise_for_status()
result = response.json()
print(result["data"])Node.js
const response = await fetch("https://api.easyx.ai/api/v3/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer easyx_ws_xxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "doubao-seedream-5-0-pro",
prompt: "A dog wearing a red hat",
}),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
console.log(result.data);