Seedream Image Generation & Editing

Overview

Seedream is the flagship image-generation model series from ByteDance BytePlus ModelArk, with a unified generation-editing architecture: text-to-image, single-image editing, multi-image fusion, and batch sequence generation all run through one /v1/images/generations endpoint — only the parameters differ. APIYI has a strategic partnership with BytePlus and integrates every active version on day one.

🎨 Highlights: three active versions (5.0 / 4.5 / 4.0) on unified billing + 4K output + up to 10 reference images for fusion + batch (input + output ≤ 15) + leading text rendering. Ideal for e-commerce hero images, ad posters, product photography, and content creation — anywhere high quality plus readable text matters.

Text-to-Image API

POST /v1/images/generations. Generate images from prompts at 1K / 2K / 3K / 4K or exact pixel sizes.

Image Editing API

Same endpoint with image parameter. Single-image editing, multi-image fusion, and batch sequence (up to 15 images).

Historical Versions

5.0 / 4.5 / 4.0 spec comparison, pricing differences, and migration guide.

Why APIYI’s Seedream

Drop-in replacement for the BytePlus ModelArk official channel, optimized for production use along three axes — stability, cost, integration:

Strategic partnership · stable resources

Authorized direct connection to BytePlus ModelArk. Request and response behavior is identical to the upstream — no protocol bypass, safe for production.

Unlimited concurrency · enterprise-ready

Linear scaling for batch generation, multi-image fusion, and sequence generation — no Tier-style account limits. Default 500 RPM, contact sales for higher quotas.

Same price + up to 20% off via top-ups

Default unit price matches BytePlus official pricing. Combined with top-up bonuses, the effective price drops to as low as 80% of list.

Global zero-friction access

No overseas server or proxy required. Connects directly to api.apiyi.com from mainland China data centers, residential networks, and overseas nodes. No need to set up routing for BytePlus ap-southeast-1 / eu-west-1 regions.

OpenAI-compatible · zero code change

The path /v1/images/generations is identical to OpenAI. Point the OpenAI SDK’s base_url at APIYI and call the API as-is. Pass extension parameters (image / sequential_image_generation etc.) via extra_body.

Professional support · enterprise concierge

Deep expertise in image-generation use cases — multi-image fusion, text rendering, batch asset production. End-to-end support from PoC to production rollout.

Key Features

4K high-fidelity output

4.0 / 4.5 support native 4K (4096×4096) with rich detail layers — ideal for posters and print. 5.0-lite tops out at 3K but offers a more refined overall experience.

Unified generation-editing

Text-to-image, single-image editing, multi-image fusion, and batch sequence all share one endpoint and one parameter set. Switch modes via image and sequential_image_generation.

Multi-image fusion · up to 10 references

image accepts a URL array. Refer to “image 1 / image 2” in the prompt for explicit ordering. Pair with sequential_image_generation: "disabled" for subject-consistent fusion.

Text rendering breakthrough

The 4.5 release dramatically improved small-text legibility. Posters, ad copy, and product text are clear and accurate — best in class.

Batch sequence (up to 15)

sequential_image_generation: "auto" plus max_images outputs a coherent series — perfect for storyboards, brand visuals, and product series.

≈ 15s per image · balanced speed

Typical single-image latency is ~15s; 4K + hd may extend up to a minute. 500 RPM default, scalable on request.

Flexible sizes · arbitrary aspect

Resolution presets (1K/2K/3K/4K) or exact pixels. Total pixels ∈ [1280×720, 4096×4096], aspect ratio ∈ [1/16, 16].

Drop-in OpenAI SDK

Set base_url=https://api.apiyi.com/v1 and call with the official OpenAI SDK. Extension params go through extra_body. Zero code change for migration.

Pricing

Per-image billing, same price as BytePlus official. Top-up bonuses lower the effective unit price further.

Model	APIYI Price	List Price (RMB est.)	Status
`seedream-5-0-260128`	$0.035 / image	≈ ¥0.245 / image	✅ Recommended (latest)
`seedream-4-5-251128`	$0.04 / image	≈ ¥0.28 / image	✅ Recommended
`seedream-4-0-250828`	$0.03 / image	≈ ¥0.21 / image	🟡 Maintained (still callable)

Billing notes:

Billed per generated image, regardless of prompt length or fusion mode
In sequential_image_generation: "auto" mode, billing is by actual output count (e.g. max_images: 4 outputs 4 → 4 billed)
Failed requests (4xx / blocked by moderation) are not billed
Free trial: 200 free images on first onboarding (provided by BytePlus)
Top-up bonus details: see Top-up Promotions

Technical Specs

Dimension	seedream-5-0	seedream-4-5	seedream-4-0
Model ID	`seedream-5-0-260128`	`seedream-4-5-251128`	`seedream-4-0-250828`
Model ID alias	`seedream-5-0-lite-260128`	—	—
Release date	2026-01-28 (UTC+8)	2025-11-28 (UTC+8)	2025-08-28 (UTC+8)
Resolution tiers	2K / 3K	2K / 4K	1K / 2K / 4K
Output format	`png` / `jpeg`	`jpeg`	`jpeg`
Prompt optimization	standard	standard	standard / fast
Text-to-image	✅	✅	✅
Single-image editing	✅	✅	✅
Multi-image fusion	✅	✅ (up to 10)	✅
Batch sequence	✅	✅	✅
Streaming output	✅	✅	✅
Max images per minute (RPM)	500	500	500
Single-request input + output	≤ 15	≤ 15	≤ 15
Response field	`data[].url` or `data[].b64_json`	same	same

API Endpoints

Endpoint	Purpose	Content-Type
`POST /v1/images/generations`	Text-to-image / single-image editing / multi-image fusion / batch sequence — all modes share one endpoint, switched via request body params	`application/json`

Domain choice: api.apiyi.com is the primary endpoint. vip.apiyi.com and other gateway domains are also available, with identical behavior. You do not need to use BytePlus native domains like ark.ap-southeast.bytepluses.com / ark.eu-west.bytepluses.com — APIYI normalizes everything to OpenAI-compatible paths.

Key Parameters in Detail

`size` (output size)

Two value families — pick one: Preset tiers (model decides aspect ratio):

Tier	Approx pixels	Supported by
`1K`	~1024×1024	4.0 only
`2K`	~2048×2048 (default)	5.0 / 4.5 / 4.0
`3K`	~3072×3072	5.0 only
`4K`	~4096×4096	4.5 / 4.0

Exact pixels (custom):

Total pixels ∈ [1280×720, 4096×4096]
Aspect ratio ∈ [1/16, 16]
Default: 2048x2048

Valid examples: 1920x1080 (FullHD), 3840x2160 (landscape 4K), 1080x1920 (phone portrait), 2560x1440 (landscape 2K) Invalid examples: 5000x5000 (over the cap), 100x1600 (aspect under 1/16)

Sizes with total pixels above 4096×4096 return 400. Extreme aspect ratios (close to 1/16 or 16) may stretch unnaturally — prefer presets or common 16:9 / 9:16 / 1:1.

`image` and `sequential_image_generation` (mode switches)

The /v1/images/generations endpoint covers both text-to-image and editing/fusion. Two parameters together select the mode:

Mode	`image`	`sequential_image_generation`	Notes
Pure text-to-image	omitted	omitted or `"disabled"`	1 output
Single-image editing	`["url1"]`	`"disabled"`	Edit based on 1 reference
Multi-image fusion	`["url1", "url2", ...]`	`"disabled"`	Up to 10 references; refer as “image 1 / image 2”
Batch sequence	optional	`"auto"` + `sequential_image_generation_options.max_images`	N coherent outputs, N ≤ max_images and input + output ≤ 15

For full code examples, see Text-to-Image and Image Editing.

Best Practices

Pick the right version

Best overall experience → seedream-5-0-260128 (most features, but 3K cap)
4K + strong text rendering → seedream-4-5-251128 (4K + text breakthrough)
4K + best price → seedream-4-0-250828 (cheapest 4K)

Prefer preset sizes

1K/2K/3K/4K are tuned by BytePlus for stable speed and quality. Use exact pixels only when you have a real aspect requirement. Note version differences in supported tiers.

Refer to images explicitly

With multiple image URLs, write the prompt with explicit references — “Place the person from image 1 into the scene of image 2 using the colour palette of image 3” — instead of letting the model guess.

Control batch sequence cost

sequential_image_generation: "auto" + max_images: 4 outputs 4 — billed × 4. Validate with max_images: 1 first, then scale up.

Pick output format by use case

5.0 supports png and jpeg; 4.5 / 4.0 only jpeg. Use 5.0 + png when you need transparent backgrounds or lossless detail, jpeg for size-sensitive scenarios.

Set client timeout ≥ 60 seconds

Single image is ~15s, but batch sequence (4 images) or 4K + hd may take 30-60s. Start with a 60s client timeout and show progress feedback in the UI.

Disable watermark when needed

Set watermark: false to remove the BytePlus watermark (defaults vary by version, so set it explicitly). Required for commercial assets.

Error Codes & Retries

Status	Meaning	Recommended action
`400`	Invalid parameters (size out of bounds, `image` array > 10, unsupported tier)	Validate against the supported tier of the version in use
`401`	Invalid token	Check Bearer Token
`403`	Blocked by content moderation	Adjust prompt or replace reference images
`429`	Rate limit (default 500 RPM) or insufficient balance	Exponential backoff; contact sales for higher RPM
`5xx`	Gateway / upstream error	Retry 1-2 times
Timeout	Long-tail request	Client timeout ≥ 60s (batch sequence or 4K + hd may reach 60s)

Client recommendations:

Start with a 60-second request timeout (batch sequence or 4K + hd may take a minute)
Apply exponential backoff for 5xx and timeouts (suggested 2 retries)
Log the x-request-id response header for support tickets

FAQ

5.0 / 4.5 / 4.0 — which to pick?

Need	Recommended
Latest features + best overall	`seedream-5-0-260128`
4K + strong text rendering (posters, ads)	`seedream-4-5-251128`
4K + best price	`seedream-4-0-250828`
Long-running stable batch production	`seedream-4-0-250828` (proven, cheapest, fast prompt mode)

See Historical Versions for full comparison.

Why does image editing also use the generations endpoint?

Seedream uses a unified generation-editing architecture — there is no separate /v1/images/edits endpoint. Unlike OpenAI’s gpt-image-2 (multipart upload to /v1/images/edits), Seedream uses application/json and passes image URLs as an array in the image field.Benefits: protocol consistency, parameter reuse, easy mode switching. See Image Editing for details.

Does the image field accept base64?

The official docs only show URL arrays. If your images are local, upload to OSS or a public image host first. For private hosting, contact sales to discuss signed-URL approaches.

Multi-image fusion limit? Batch sequence limit?

Multi-image fusion (image array): 4.5 explicitly supports up to 10. 5.0 / 4.0 also support multi-image, though no explicit ceiling is documented.
Batch sequence (max_images): bounded by the global rule input references + output ≤ 15. When combining fusion and sequence, count the total.

Does b64_json need a data:image prefix?

Depends on response_format:

response_format: "url" (default) → data[0].url is a temp signed URL, render directly with <img src=...>
response_format: "b64_json" → data[0].b64_json is a plain base64 string (no data:image/...;base64, prefix). Decode and write to disk, or prepend the prefix manually for browser rendering.

Is streaming output supported?

Yes. All three versions are marked “Streaming output ✅”. Set stream: true. Streaming is especially useful for long prompts and high-resolution images — the frontend can render partial results progressively.

Rate limit?

Default 500 images per minute (Max Images per Minute), unified across versions. Contact sales for higher quotas.

Are failed requests billed?

No. BytePlus has built-in moderation. Moderation rejects and parameter errors return 400 / 403 and are not billed. Other zero-billed errors: 401 (invalid token), 429 (rate limited). Only successful generation (200 with valid response) is billed.

Can I use the official OpenAI SDK?

Yes, with no code changes. Point base_url at https://api.apiyi.com/v1 and pass extension params (image / sequential_image_generation / watermark etc.) via extra_body:

from openai import OpenAI

client = OpenAI(api_key="sk-your-key", base_url="https://api.apiyi.com/v1")
resp = client.images.generate(
    model="seedream-5-0-260128",
    prompt="...",
    size="2K",
    extra_body={
        "image": ["https://.../ref.png"],
        "sequential_image_generation": "disabled",
        "watermark": False,
    }
)

Who owns the generated images?

Generated images can be used commercially and non-commercially. See the BytePlus terms of service for details.

Are transparent backgrounds supported?

seedream-5-0 supports png output and can produce transparent backgrounds when prompted (“transparent background, alpha channel”). seedream-4-5 / 4-0 output only jpeg and do not support transparency — post-process to remove the background yourself.

Can I cancel a generation in flight?

No. /v1/images/generations is synchronous. Once submitted, the request runs to completion. The server still completes and bills even if the client disconnects. Set client timeouts and avoid the assumption that disconnect saves cost.

Text-to-Image Playground — POST /v1/images/generations with five language code samples
Image Editing Playground — image + sequential_image_generation patterns
Historical Versions — 5.0 / 4.5 / 4.0 comparison and migration
API Manual — general invocation guide
Image Generation Sandbox — try it online
BytePlus official docs: docs.byteplus.com/en/docs/ModelArk/1824121 — Seedream 4.0-5.0 tutorial

Seedream is provided through APIYI’s strategic partnership with BytePlus ModelArk. Three versions share a single integration, billing, and authentication path — pick by need. For questions or feedback, file a ticket from the console.

Basics

Basic API

Image API

Video API

Multimodal Understanding API

Text API

Seedream Image Generation & Editing

Overview

Text-to-Image API

Image Editing API

Historical Versions

Why APIYI’s Seedream

Strategic partnership · stable resources

Unlimited concurrency · enterprise-ready

Same price + up to 20% off via top-ups

Global zero-friction access

OpenAI-compatible · zero code change

Professional support · enterprise concierge

Key Features

4K high-fidelity output

Unified generation-editing

Multi-image fusion · up to 10 references

Text rendering breakthrough

Batch sequence (up to 15)

≈ 15s per image · balanced speed

Flexible sizes · arbitrary aspect

Drop-in OpenAI SDK

Pricing

Technical Specs

API Endpoints

Key Parameters in Detail

`size` (output size)

`image` and `sequential_image_generation` (mode switches)

Best Practices

Error Codes & Retries

FAQ

Basics

Basic API

Image API

Video API

Multimodal Understanding API

Text API

​Overview

Text-to-Image API

Image Editing API

Historical Versions

​Why APIYI’s Seedream

Strategic partnership · stable resources

Unlimited concurrency · enterprise-ready

Same price + up to 20% off via top-ups

Global zero-friction access

OpenAI-compatible · zero code change

Professional support · enterprise concierge

​Key Features

4K high-fidelity output

Unified generation-editing

Multi-image fusion · up to 10 references

Text rendering breakthrough

Batch sequence (up to 15)

≈ 15s per image · balanced speed

Flexible sizes · arbitrary aspect

Drop-in OpenAI SDK

​Pricing

​Technical Specs

​API Endpoints

​Key Parameters in Detail

​size (output size)

​image and sequential_image_generation (mode switches)

​Best Practices

​Error Codes & Retries

​FAQ

​Related Docs

Overview

Why APIYI’s Seedream

Key Features

Pricing

Technical Specs

API Endpoints

Key Parameters in Detail

`size` (output size)

`image` and `sequential_image_generation` (mode switches)

Best Practices

Error Codes & Retries

FAQ

Related Docs