图片编辑 API 参考

Seedream 图片编辑 / 多图融合 / 批量序列生成 API 参考与在线调试 — 同 generations 端点，传入 image 数组与 sequential_image_generation 切换模式

POST /v1/images/generations

图片编辑 / 多图融合 / 批量序列

cURL

curl --request POST \
  --url https://api.apiyi.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "seedream-5-0-260128",
  "prompt": "Replace the clothing in image 1 with the outfit from image 2."
}
'

200

{
  "model": "seedream-5-0-260128",
  "created": 1768518000,
  "data": [
    {
      "url": "https://ark-content-generation-v2-ap-southeast-1.tos-ap-southeast-1.bytepluses.com/.../image.png",
      "b64_json": "<string>",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 6240,
    "total_tokens": 6240
  }
}

同端点，不同模式：Seedream 没有独立的 /v1/images/edits 端点，编辑 / 多图融合 / 批量序列都走 POST /v1/images/generations。本页 Playground 与 文生图页 调的是同一个端点，区别只在请求体的 image 与 sequential_image_generation 参数。

场景说明：

• 单图编辑 —— image: ["url"] + sequential_image_generation: "disabled"
• 多图融合 —— image: ["url1", "url2", ...] + sequential_image_generation: "disabled"
• 批量序列生成 —— sequential_image_generation: "auto" + sequential_image_generation_options.max_images: N
• 图生序列 —— 上面两个组合：传 image 数组 + auto + max_images

🖥️ 浏览器 Playground 限制（仅 b64_json 模式）

默认 response_format: "url" 模式下 Playground 工作正常（响应只是一个 BytePlus TOS 临时链接）。如果你切换成 response_format: "b64_json"，响应会包含数 MB 的 base64 字符串，浏览器 Playground 可能弹出 请求时发生错误: unable to complete request ——实际请求已经成功，只是浏览器无法显示这么长的 base64。

推荐做法：

• 只想看图：保持默认 url 模式，Playground 会直接返回链接（注意 24 小时内下载到自己的存储）。
• 真的需要 b64_json：复制下方”代码示例”到本地运行，代码会自动解码并把图片保存为本地文件。

⚠️ 关键差异（与 OpenAI gpt-image-2 的图编辑不同）

• 不接受 multipart/form-data 上传文件 —— 请把图片传到 OSS / 公网图床拿到 URL，再放进 image 数组
• image 是 URL 数组，不是 image[] 字段重复（与 OpenAI gpt-image-2 的 multipart/form-data 格式完全不同）
• 没有 mask 字段 —— Seedream 不支持 alpha 通道掩码局部重绘，整图 prompt 改写
• 总张数硬约束：输入参考图 + 输出图 ≤ 15 张

📎 多图融合顺序有意义

image 数组的顺序会作为 prompt 中「图1/图2/图3」的引用依据。建议在 prompt 中显式指代：

Replace the clothing in image 1 with the outfit from image 2, keeping the lighting from image 3.

推荐 prompt 用英文（官方训练以英文为主），中文也可用但表达不要含糊。

​

代码示例

关于 extra_body（重要，别被「套一层」误导）

image、sequential_image_generation、watermark 不是 OpenAI SDK images.generate() 的标准参数，所以在 Python SDK 里必须放进 extra_body 才能传出去。

但 extra_body 只是 SDK 的传参容器——里面的字段会被平铺合并到请求体顶层，和 model、prompt 同一层级。最终发出去的 JSON 跟下方 cURL 示例完全一致（image 就在顶层），并不会真的多出一层 "extra_body": {...} 嵌套。

如果你不用 OpenAI SDK、而是直接拼 JSON（requests / fetch 等），就不要写 extra_body，直接把 image 等字段放到与 model 同级即可。

​

Python（OpenAI SDK · 单图编辑）

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.apiyi.com/v1"
)

resp = client.images.generate(
    model="seedream-5-0-260128",
    prompt="Generate a close-up image of a dog lying on lush grass.",
    size="2K",
    response_format="url",
    # extra_body 里的字段会被 SDK 平铺到请求体顶层（与 model 同级），不是真的多嵌套一层
    extra_body={
        "image": ["https://your-oss.example.com/source-photo.png"],
        "sequential_image_generation": "disabled",
        "watermark": False,
    }
)

print(resp.data[0].url)

​

Python（OpenAI SDK · 多图融合）

resp = client.images.generate(
    model="seedream-4-5-251128",
    prompt="Replace the clothing in image 1 with the outfit from image 2, keeping the lighting style of image 3.",
    size="4K",
    response_format="url",
    extra_body={
        "image": [
            "https://your-oss.example.com/person.png",
            "https://your-oss.example.com/outfit.png",
            "https://your-oss.example.com/lighting-ref.png",
        ],
        "sequential_image_generation": "disabled",
        "watermark": False,
    }
)

print(resp.data[0].url)

​

Python（OpenAI SDK · 批量序列生成）

resp = client.images.generate(
    model="seedream-5-0-260128",
    prompt=(
        "Generate four cinematic sci-fi storyboard scenes:"
        "Scene 1 — astronaut repairing a spacecraft;"
        "Scene 2 — meteor strike in deep space;"
        "Scene 3 — emergency dodge in zero gravity;"
        "Scene 4 — astronaut returning to ship."
    ),
    size="2K",
    response_format="url",
    extra_body={
        "sequential_image_generation": "auto",
        "sequential_image_generation_options": {"max_images": 4},
        "watermark": False,
    }
)

for item in resp.data:
    print(item.url)

​

cURL（多图融合）

curl -X POST "https://api.apiyi.com/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-260128",
    "prompt": "Replace the clothing in image 1 with the outfit from image 2.",
    "image": [
      "https://your-oss.example.com/person.png",
      "https://your-oss.example.com/outfit.png"
    ],
    "sequential_image_generation": "disabled",
    "size": "2K",
    "response_format": "url",
    "watermark": false
  }'

​

Node.js（原生 fetch · 批量序列）

const resp = await fetch('https://api.apiyi.com/v1/images/generations', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer sk-your-api-key'
    },
    body: JSON.stringify({
        model: 'seedream-5-0-260128',
        prompt: 'A four-panel comic about a cat astronaut: launch, space walk, alien encounter, return home.',
        size: '2K',
        sequential_image_generation: 'auto',
        sequential_image_generation_options: { max_images: 4 },
        response_format: 'url',
        watermark: false
    })
});

const { data } = await resp.json();
data.forEach((item, i) => console.log(`#${i + 1}:`, item.url));

​

参数说明速查

字段	类型	必填	默认	说明
model	string	是	—	seedream-5-0-260128 / seedream-4-5-251128 / seedream-4-0-250828
prompt	string	是	—	编辑 / 融合 / 序列指令
image	array of string (URL)	否（编辑场景必填）	—	参考图 URL 数组，最多 10 张（4.5 官方明确）
sequential_image_generation	string	否	disabled	disabled 单图输出；auto 批量序列输出
sequential_image_generation_options.max_images	integer	否	—	仅 auto 模式生效，输出张数（受 输入+输出 ≤ 15 总约束）
size	string	否	2K	预设档位或精确像素，各版本支持档位见 overview
response_format	string	否	url	url / b64_json
output_format	string	否	jpeg	5.0 支持 png / jpeg；4.5 / 4.0 仅 jpeg
watermark	boolean	否	见版本默认	商用建议 false
stream	boolean	否	false	流式输出，长 prompt 时建议开

​

多图与批量场景的张数约束

场景	输入 image 张数	max_images	实际输出	总和约束
单图编辑	1	—	1	2 ≤ 15 ✅
多图融合	3	—	1	4 ≤ 15 ✅
多图融合 + 序列	3	4	4	7 ≤ 15 ✅
多图融合 + 序列	10	6	6	16 > 15 ❌ 报错

多轮迭代：把上一次的输出 URL 作为下一次的 image 输入，配合新的编辑指令逐步精调。每一轮都按张计费，预算时留意累计成本。

​

响应格式

{
  "model": "seedream-5-0-260128",
  "created": 1768518000,
  "data": [
    {
      "url": "https://ark-content-generation-v2-ap-southeast-1.tos-ap-southeast-1.bytepluses.com/seedream-5-0/.../scene-1.png",
      "size": "2048x2048"
    },
    {
      "url": "https://...scene-2.png",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 2,
    "output_tokens": 12480,
    "total_tokens": 12480
  }
}

⚠️ data 数组长度反映实际输出张数

• sequential_image_generation: "disabled" → data 单元素
• sequential_image_generation: "auto" + max_images: N → data 通常 N 个元素（个别 prompt 模型可能输出少于 N）
• 计费按 usage.generated_images 实际张数算，不是按 max_images

编辑请求和文生图请求计费完全一致——按出图张数算。多图输入（参考图）不额外计费。

授权

Authorization · string · header · 必填

在 API易控制台获取的 API Key

请求体

application/json

model · enum<string> · 默认值: seedream-5-0-260128 · 必填

模型 ID

可用选项: seedream-5-0-260128, seedream-5-0-lite-260128, seedream-4-5-251128, seedream-4-0-250828

prompt · string · 必填

编辑 / 融合 / 序列指令。多图场景建议用「图1/图2」明确指代顺序

示例:

"Replace the clothing in image 1 with the outfit from image 2."

image · string<uri>[]

参考图 URL 数组。最多 10 张（4.5 官方明确）。注意输入 + 输出张数总和 ≤ 15

Maximum array length: 10

示例:

[
  "https://your-oss.example.com/person.png",
  "https://your-oss.example.com/outfit.png"
]

sequential_image_generation · enum<string> · 默认值: disabled

图像生成模式开关。disabled = 单图输出（默认）；auto = 批量序列输出，配合 max_images 指定张数

可用选项: disabled, auto

sequential_image_generation_options · object

批量序列生成选项，仅 sequential_image_generation=auto 时生效

Show child attributes

size · string · 默认值: 2K

输出尺寸。预设档位（各版本支持不同）：

• 1K（仅 4.0）/ 2K（全版本）/ 3K（仅 5.0）/ 4K（4.5、4.0）

或精确像素 WxH，总像素 ∈ [1280×720, 4096×4096]，宽高比 ∈ [1/16, 16]

示例:

"2K"

response_format · enum<string> · 默认值: url

可用选项: url, b64_json

output_format · enum<string> · 默认值: jpeg

输出格式。5.0 支持 png / jpeg；4.5 / 4.0 仅 jpeg

可用选项: png, jpeg

watermark · boolean · 默认值: false

stream · boolean · 默认值: false

流式输出。长 prompt 或多图序列场景建议开启

响应

200

application/json

成功生成编辑后图片

model · string

示例:

"seedream-5-0-260128"

created · integer

示例:

1768518000

data · object[]

生成结果数组。disabled 模式 1 个元素，auto 模式通常 max_images 个元素（实际可能少于）

Show child attributes

usage · object

按 generated_images 实际张数计费，不是按 max_images

Show child attributes