Image Editing API Reference

Seedream image editing, multi-image fusion, and batch sequence generation API reference and live Playground — same generations endpoint, switched via the image array and sequential_image_generation parameter

POST /v1/images/generations

Image Editing / Multi-image Fusion / Batch Sequence

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

One endpoint, multiple modes: Seedream has no separate /v1/images/edits endpoint. Editing, multi-image fusion, and batch sequence all run through POST /v1/images/generations. This page’s Playground hits the same endpoint as Text-to-Image — the only difference is the image and sequential_image_generation parameters in the body.

Modes:

• Single-image editing — image: ["url"] + sequential_image_generation: "disabled"
• Multi-image fusion — image: ["url1", "url2", ...] + disabled
• Batch sequence — sequential_image_generation: "auto" + sequential_image_generation_options.max_images: N
• Image-to-sequence — combine the two: image array + auto + max_images

🖥️ Browser Playground limitation (b64_json mode only)

In the default response_format: "url" mode, the Playground works fine (the response is just a temporary BytePlus TOS link). If you switch to response_format: "b64_json", the response contains a multi-MB base64 string and the browser Playground may show 请求时发生错误: unable to complete request — the request actually succeeded; the browser just can’t render such a long base64 string.

Recommended workflow:

• Just want to view the image? Keep the default url mode — the Playground returns the link directly (remember to download to your own storage within 24 hours).
• Need b64_json? Copy the code sample below and run it locally — the code will decode and save the image to a file automatically.

⚠️ Key differences vs. OpenAI gpt-image-2 editing

• No multipart/form-data uploads — upload your images to OSS or a public image host first, then pass URLs in the image array
• image is a URL array, not a repeated image[] field (unlike OpenAI’s multipart/form-data format)
• No mask field — Seedream does not support alpha-channel mask inpainting; the whole image is rewritten by the prompt
• Hard limit on total count: input references + output ≤ 15 images

📎 Multi-image order matters

The order of URLs in the image array becomes the “image 1 / image 2 / image 3” referenced in the prompt. Make ordering explicit:

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

English prompts work best (the model is trained primarily on English), but Chinese is also supported as long as the wording is unambiguous.

Code Examples

About extra_body (important — don’t be misled into thinking it’s an extra nesting layer)

image, sequential_image_generation, and watermark are not standard parameters of the OpenAI SDK’s images.generate(), so in the Python SDK you must put them inside extra_body to send them.

But extra_body is just the SDK’s parameter container — its fields are flattened and merged into the top level of the request body, at the same level as model and prompt. The JSON that actually goes out is identical to the cURL example below (image sits at the top level); there is no real "extra_body": {...} nesting in the request.

If you’re not using the OpenAI SDK and instead build the JSON directly (requests / fetch / etc.), do not write extra_body — just place image and the other fields at the same level as model.

Python (OpenAI SDK · single-image editing)

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",
    # Fields in extra_body are flattened to the top level of the request body
    # (same level as model) by the SDK — not an extra nesting layer
    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 · multi-image fusion)

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 · batch sequence)

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 (multi-image fusion)

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 · batch sequence)

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

Parameter Reference

Parameter	Type	Required	Default	Description
model	string	yes	—	seedream-5-0-260128 / seedream-4-5-251128 / seedream-4-0-250828
prompt	string	yes	—	Editing / fusion / sequence instruction
image	array of URL	required for editing	—	Reference image URLs, up to 10 (per official 4.5 docs)
sequential_image_generation	string	no	disabled	disabled for single output; auto for batch sequence
sequential_image_generation_options.max_images	integer	no	—	Effective only with auto. Subject to input + output ≤ 15
size	string	no	2K	Preset tier or exact pixels — tier support varies by version (see Overview)
response_format	string	no	url	url / b64_json
output_format	string	no	jpeg	5.0 supports png / jpeg; 4.5 / 4.0 only jpeg
watermark	boolean	no	varies	Set false for commercial use
stream	boolean	no	false	Streaming output, recommended for long prompts

Count Constraints in Multi-image and Sequence Modes

Scenario	Input image count	max_images	Actual output	Total constraint
Single-image editing	1	—	1	2 ≤ 15 ✅
Multi-image fusion	3	—	1	4 ≤ 15 ✅
Multi-image fusion + sequence	3	4	4	7 ≤ 15 ✅
Multi-image fusion + sequence	10	6	6	16 > 15 ❌ rejected

Iterative refinement: feed a previous output’s URL as the next input, with a fresh edit instruction, to refine progressively. Each round is billed per image — watch cumulative cost.

Response Format

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

⚠️ The data array length reflects actual output count

• sequential_image_generation: "disabled" → single-element data
• sequential_image_generation: "auto" + max_images: N → typically N elements (occasionally fewer if the prompt produces less)
• Billing is by usage.generated_images, not by max_images

Editing requests are billed identically to text-to-image — per output image. Reference image inputs are not separately billed.

Authorizations

Authorization · string · header · required

API Key obtained from APIYI Console

Body

application/json

model · enum<string> · default: seedream-5-0-260128 · required

Model ID

Available options: seedream-5-0-260128, seedream-5-0-lite-260128, seedream-4-5-251128, seedream-4-0-250828

prompt · string · required

Editing / fusion / sequence instruction. For multi-image scenarios, refer to images explicitly as 'image 1 / image 2'

Example:

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

image · string<uri>[]

Reference image URL array. Up to 10 images (per official 4.5 docs). Note: input + output count ≤ 15

Maximum array length: 10

Example:

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

sequential_image_generation · enum<string> · default: disabled

Generation mode switch. disabled = single output (default); auto = batch sequence, paired with max_images

Available options: disabled, auto

sequential_image_generation_options · object

Batch sequence options. Effective only when sequential_image_generation=auto

Show child attributes

size · string · default: 2K

Output size. Preset tiers (vary by version):

• 1K (4.0 only) / 2K (all) / 3K (5.0 only) / 4K (4.5, 4.0)

Or exact pixel size WxH, total pixels ∈ [1280×720, 4096×4096], aspect ratio ∈ [1/16, 16]

Example:

"2K"

response_format · enum<string> · default: url

Available options: url, b64_json

output_format · enum<string> · default: jpeg

Output format. 5.0 supports png/jpeg; 4.5/4.0 only jpeg

Available options: png, jpeg

watermark · boolean · default: false

stream · boolean · default: false

Streaming output. Recommended for long prompts and multi-image sequence scenarios

Response

200

application/json

Edited image generated successfully

model · string

Example:

"seedream-5-0-260128"

created · integer

Example:

1768518000

data · object[]

Result array. disabled mode returns 1 element; auto mode typically returns max_images elements (may be fewer)

Show child attributes

usage · object

Billed by generated_images actual count, NOT by max_images

Show child attributes