Image Editing API Reference

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

⚠️ 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 mattersThe 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

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

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

Basics

Basic API

Image API

Video API

Multimodal Understanding API

Text API

Code Examples

Python (OpenAI SDK · single-image editing)

Python (OpenAI SDK · multi-image fusion)

Python (OpenAI SDK · batch sequence)

cURL (multi-image fusion)

Node.js (fetch · batch sequence)

Parameter Reference

Count Constraints in Multi-image and Sequence Modes

Response Format

Authorizations

Body

Response

Basics

Basic API

Image API

Video API

Multimodal Understanding API

Text API

​Code Examples

​Python (OpenAI SDK · single-image editing)

​Python (OpenAI SDK · multi-image fusion)

​Python (OpenAI SDK · batch sequence)

​cURL (multi-image fusion)

​Node.js (fetch · batch sequence)

​Parameter Reference

​Count Constraints in Multi-image and Sequence Modes

​Response Format

Authorizations

Body

Response

Code Examples

Python (OpenAI SDK · single-image editing)

Python (OpenAI SDK · multi-image fusion)

Python (OpenAI SDK · batch sequence)

cURL (multi-image fusion)

Node.js (fetch · batch sequence)

Parameter Reference

Count Constraints in Multi-image and Sequence Modes

Response Format