Skip to main content
POST
Seedream 5.0 Pro · Image to image

Introduction

Provide reference images and editing instructions for single-image editing, multi-image fusion, interactive editing, transparency, or layer decomposition. Ordinary editing returns one image; decomposition returns a base image and multiple layers.

Endpoint and authentication

Use Authorization: Bearer sk-xxxxxxxxxx and Content-Type: application/json. Image editing also accepts /v1/images/edits with the same JSON body. Parameters and pricing

Request parameters

For ordinary generation, omit n or use 1; send separate requests for multiple results. See shared parameters for full defaults and safety_identifier. Neither model supports quality, sequential generation, streaming, or web search.

prompt

Required for editing. Describe how to use or change the reference images. Optional for decomposition: specify elements to separate, or omit to let the model identify the main elements. Keep Chinese prompts within 300 characters and English prompts within 600 words; overly long prompts may dilute details. For interactive editing, identify a region with <bbox>x1 y1 x2 y2</bbox> using normalized [0, 1000] coordinates, with the origin at the top-left. Alternatively, draw boxes, arrows, or sketches on the reference and describe the intended changes.

image

Accepts one string or an array of strings. Each entry is a server-accessible public URL or Base64 data URI in the form data:image/<format>;base64,<data>; use lowercase format names, for example data:image/png;base64,iVBORw0....
Total pixels means width × height, not independent minimum dimensions. Transparency constraints are listed separately below.

size

Full size rules and dimension table Decomposition supports only 1K, 1.5K, 2K, and auto (default); custom pixel dimensions are not supported.

background

5.0 Pro does not support text-only transparent output. Transparent editing requires exactly one reference image with an existing alpha channel.
Never combine background: "transparent" with JPEG output. Do not pass background in decomposition mode.

layer_decomposition

Set layer_decomposition: true to split one image into one base image and up to 16 independent PNG layers with alpha channels. Default: false.
  • image is required; exactly one input is accepted.
  • Any layer failure fails the entire request; partial success is not supported.
  • Requested layers beyond the limit may be omitted.
  • The response includes z_index, name, description, and bounding_box.
  • The base image and all layers are counted in usage.generated_images.

Request examples

Each example includes a complete JSON body and matching cURL. Replace sk-xxxxxxxxxx with your API Key. Input URLs are public and need no login. Response URLs illustrate structure only.

Single-image editing

Multi-image fusion

Interactive editing

Transparent image editing

Layer decomposition

Success response

Ordinary editing uses the shared response; usage.input_images reflects actual reference count. The excerpt below shows only the base image and one layer, while usage describes the full result. Therefore its generated_images exceeds the number of entries shown. URLs are illustrative. Shared response

Response fields

Shared response fields
Reconstruct layers: resize each layer to (right - left) × (bottom - top) using absolute coordinates, then place it at (left, top) on the base image. For normalized coordinates on a W × H canvas, the top-left position is (left / 1000 × W, top / 1000 × H). Stack layers in ascending z_index order.
Result URLs expire after 24 hours. Download and persist them immediately.

Pricing and errors

Reference images and outputs are billed separately; the base image and each layer count as individual outputs. Pricing · Error handling