图片编辑 API 参考

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

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."
}
'

import requests

url = "https://api.apiyi.com/v1/images/generations"

payload = {
    "model": "seedream-5-0-260128",
    "prompt": "Replace the clothing in image 1 with the outfit from image 2."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'seedream-5-0-260128',
    prompt: 'Replace the clothing in image 1 with the outfit from image 2.'
  })
};

fetch('https://api.apiyi.com/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apiyi.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'seedream-5-0-260128',
    'prompt' => 'Replace the clothing in image 1 with the outfit from image 2.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apiyi.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"seedream-5-0-260128\",\n  \"prompt\": \"Replace the clothing in image 1 with the outfit from image 2.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"seedream-5-0-260128\",\n  \"prompt\": \"Replace the clothing in image 1 with the outfit from image 2.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apiyi.com/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"seedream-5-0-260128\",\n  \"prompt\": \"Replace the clothing in image 1 with the outfit from image 2.\"\n}"

response = http.request(request)
puts response.read_body

{
  "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
  }
}

POST

images

generations

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

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."
}
'

import requests

url = "https://api.apiyi.com/v1/images/generations"

payload = {
    "model": "seedream-5-0-260128",
    "prompt": "Replace the clothing in image 1 with the outfit from image 2."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'seedream-5-0-260128',
    prompt: 'Replace the clothing in image 1 with the outfit from image 2.'
  })
};

fetch('https://api.apiyi.com/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apiyi.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'seedream-5-0-260128',
    'prompt' => 'Replace the clothing in image 1 with the outfit from image 2.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apiyi.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"seedream-5-0-260128\",\n  \"prompt\": \"Replace the clothing in image 1 with the outfit from image 2.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"seedream-5-0-260128\",\n  \"prompt\": \"Replace the clothing in image 1 with the outfit from image 2.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apiyi.com/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"seedream-5-0-260128\",\n  \"prompt\": \"Replace the clothing in image 1 with the outfit from image 2.\"\n}"

response = http.request(request)
puts response.read_body

{
  "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));

参考图请传公网 URL，不要传 base64（2026-09-11 起重点提醒）image 数组的元素是 URL 时，请求体只有几 KB，BytePlus 会直接从新加坡机房去下载你的图片（实测下载方 IP 属于 BytePlus，不经过 API易网关）。元素是 data:image/...;base64,... 时，几张高清参考图的请求体动辄 20 到 30 MB，要先整体上传到 API易网关再转发到新加坡，跨境上传慢的时候会超过原厂入口 600 秒的请求体超时，返回 400 Error when parsing request，此时整条请求失败且不会自动切换成 URL 方式，因为网关不会替你把 base64 转成可下载的链接。

✅ 把图片放到自己的 OSS / 图床，传公网可直接 GET、无鉴权的 URL，单张建议不超过 10 MB
⚠️ 确实只能传 base64 时，先压缩：长边缩到 2048px 以内、质量 0.9 重编码，多张合计控制在 6 MB 以内
❌ 不要传 20 MB 以上的 base64 请求体，也不要传内网地址或需要登录的链接（BytePlus 下载失败会返回 InvalidParameter: Error while downloading）

参数说明速查

字段	类型	必填	默认	说明
`model`	string	是	—	`seedream-5-0-260128` / `seedream-4-5-251128` / `seedream-4-0-250828` / `seedream-5-0-pro-260628`（专业版，$0.12/次）/ `seedream-5-0-flash-260915`（快速版，$0.018/次，参考图不收费）
`prompt`	string	是	—	编辑 / 融合 / 序列指令
`image`	array of string	否（编辑场景必填）	—	参考图数组，元素为 URL 或 base64 data URI（`data:image/jpeg;base64,...`，已实测），最多 10 张（4.5 / 5.0-pro / 5.0-flash 官方明确，5.0-flash 实测第 11 张返回 400）
`sequential_image_generation`	string	否	`disabled`	`disabled` 单图输出；`auto` 批量序列输出。5.0-pro / 5.0-flash 不支持：传任何值（含 `disabled`）都返回 400，用这两款时请勿传此参数
`sequential_image_generation_options.max_images`	integer	否	—	仅 `auto` 模式生效，输出张数（受输入+输出 ≤ 15 总约束）。5.0-pro / 5.0-flash 同样不可传
`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`（5.0-flash 不传时带「AI generated」水印）
`stream`	boolean	否	`false`	流式输出，长 prompt 时建议开。5.0-pro / 5.0-flash 不支持，传入即 400

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

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

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

5.0 Flash 分层（透明图层）

seedream-5-0-flash-260915 支持把一张成品图拆成背景底图 + 多个独立元素的透明图层，适合二次排版、换背景、素材复用。直接在提示词里要求透明背景是拿不到 alpha 通道的，透明素材要走这个方式。

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-flash-260915",
    "prompt": "把图片拆分为背景和各个独立元素的图层",
    "image": ["https://your-oss.example.com/poster.jpg"],
    "layer_decomposition": true,
    "size": "1K",
    "output_format": "png",
    "response_format": "url",
    "watermark": false
  }'

实测结果（2026-09-24，UTC+8）：

传 1 张参考图，返回 data 数组共 12 张：第 1 张是抠掉元素后补全的背景底图（文件名以 _base.png 结尾，RGB），其余 11 张是 RGBA 透明图层（_layer_1.png 起），每层只含一个元素、尺寸按元素裁切
1K 一次约 78 秒；同样的请求用 2K 实测 15 分钟都没拿到结果，但账单照常扣了 12 张的 $0.216。请用 1K，并把客户端超时设到 300 秒以上
分层可能失败：同一张图有一次在约 60 秒后返回 400（the image content could not be processed for layer decomposition），失败不扣费，重试即可
底图里被移走的区域是模型补画的内容，用于商用前请人工检查

分层按输出张数计费：返回几张就计几次 $0.018。实测一次返回 12 张，扣费 $0.216（usage.generated_images 为 12）。图层数量由画面内容决定，无法事先指定，同一张图两次分层也可能不同（实测同一张图先后拆出 12 张和 14 张，分别扣 $0.216 和 $0.252），预算时按十几张估算。

响应格式

{
  "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,

seedream-5-0-pro-260628,

seedream-5-0-flash-260915

prompt

string

必填

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

示例:

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

image

string<uri>[]

参考图 URL 数组。最多 10 张（4.5 / 5.0-pro / 5.0-flash 官方明确，5.0-flash 实测第 11 张返回 400）。注意输入 + 输出张数总和 ≤ 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 指定张数。5.0-pro / 5.0-flash 不支持，传任何值都返回 400

可用选项:

disabled,

auto

sequential_image_generation_options

object

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

Show child attributes

size

string

默认值:2K

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

1K（4.0 / 5.0-pro / 5.0-flash）/ 1.5K（仅 5.0-flash）/ 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

layer_decomposition

boolean

默认值:false

仅 5.0-flash：传 1 张参考图，返回背景底图 + 多张 RGBA 透明图层。按输出张数计费（实测一次 12 张），建议 size 用 1K、超时 ≥ 300 秒

stream

boolean

默认值:false

流式输出。长 prompt 或多图序列场景建议开启。5.0-pro / 5.0-flash 不支持，传入即 400

响应

成功生成编辑后图片

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

产品基础

基础 API

图片 API（官转）

视频 API（官转）

多模态理解 API

文本生成

音频 API（官转）

检索与安全

代码示例

Python（OpenAI SDK · 单图编辑）

Python（OpenAI SDK · 多图融合）

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

cURL（多图融合）

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

参数说明速查

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

5.0 Flash 分层（透明图层）

响应格式

授权

请求体

响应

​代码示例

​Python（OpenAI SDK · 单图编辑）

​Python（OpenAI SDK · 多图融合）

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

​cURL（多图融合）

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

​参数说明速查

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

​5.0 Flash 分层（透明图层）

​响应格式

授权

请求体

响应

代码示例

Python（OpenAI SDK · 单图编辑）

Python（OpenAI SDK · 多图融合）

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

cURL（多图融合）

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

参数说明速查

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

5.0 Flash 分层（透明图层）

响应格式