圖片編輯 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 分層（透明圖層）

響應格式