Skip to main content
POST
Watermarks are always disabled. Image results use the platform URL resource format.

Completed Task Result

Poll GET /api/v1/tasks/{task_id} using the task returned by this endpoint. Images appear in data.result.resources[]. Each resource preserves format, width, height, and the upstream size and actual background in metadata. The first resource additionally contains metadata.response: created (Unix seconds), upstream model, the optional echoed safety_identifier, and the complete usage object (generated_images, input_images, output_tokens, total_tokens). These fields remain available in the public task result.

Layer Decomposition and OCR Results

Set layer_decomposition to true and provide exactly one image. The prompt is optional. layer_decomposition_max_images includes the base image and is a maximum, not a promised output count. Each output is a separate resource; retain every layer when composing the result. Font and style matches are approximate. Base images, non-text layers, handwriting, and artistic text may have no OCR result. Absence of text_recognition is valid. All layer and OCR metadata stays attached to its resource after storage and public task-result cleanup. Request-level information remains in the first resource’s metadata.response; usage.generated_images includes the base and layers.

Authorizations

Authorization
string
header
required

API Key authentication. Format: Bearer YOUR_API_KEY.

Body

application/json
prompt
string
required

Describe the desired image or editing instruction. Up to 10000 characters. Keep the instructions focused; for automatic layer decomposition this field may be omitted.

Required string length: 1 - 10000
Pattern: \S
Example:

"A detailed landscape in a 16:9 composition"

image
required

One accessible image URL or an array of 1–10 URLs. Each image: at most 30 MB, aspect ratio 1/16–16. Generation accepts JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, HEIF; width and height greater than 14 px and 196–36000000 total pixels. Decomposition accepts one PNG/JPEG only, with 262144–36000000 total pixels.

Minimum string length: 1
Example:

"https://example.com/input.png"

layer_decomposition
enum<boolean>
default:false

Split one input image into a base image and up to 99 transparent PNG layers. Omit background in this mode. The prompt becomes optional.

Available options:
true,
false
size
enum<string>
default:2K

Output resolution preset. Describe the aspect ratio in the prompt. Custom dimensions, auto, and 4K are rejected, including in layer decomposition.

Available options:
1K,
1.5K,
2K
output_format
enum<string>
default:png

Output file format. Transparent backgrounds require PNG. In decomposition this affects only the base image; all layers remain PNG.

Available options:
png,
jpeg
background
enum<string>
default:auto

Generation background mode. transparent produces RGBA and requires PNG. Omit this parameter entirely for layer decomposition; its default is not sent in that mode.

Available options:
auto,
transparent,
opaque
optimize_prompt_mode
enum<string>
default:standard

Prompt optimization mode. Seedream 5.5 supports standard only.

Available options:
standard
safety_identifier
string

Optional stable English identifier for the end user. Prefer a hash instead of personal information. The upstream value is preserved in the completed result.

Required string length: 1 - 64
Pattern: ^[\x20-\x7E]+$
layer_decomposition_max_images
integer
default:30

Maximum total output images including the base. Requires layer_decomposition=true. Mapped to upstream layer_decomposition_options.max_images.

Required range: 2 <= x <= 100
layer_decomposition_text_recognition
enum<boolean>
default:false

Request rich-text OCR for regular text layers. Requires layer_decomposition=true. Mapped to upstream layer_decomposition_options.text_recognition.

Available options:
true,
false

Response

200 - application/json

Task submitted successfully

code
integer
required

Response code, 0 indicates success

Example:

0

message
string
required

Response message

Example:

"success"

data
object
required

Detailed data about the submitted asynchronous task.