Seedream-5.5 Image Generation | ToAPIs Documentation

POST

/v1/images/generations

Note for users in mainland China: Please use https://toapis.cn as the API endpoint (Base URL). Replace https://toapis.com with https://toapis.cn in the examples in this document.

Use doubao-seedream-5-5 for text-to-image generation, reference-guided editing, or layer decomposition. Submissions return a task ID; query the task to retrieve its results.

Returns one result image per request.

Authorizations

Authorizationstringheaderrequired

All endpoints require Bearer Token authentication

Get your API Key from the API Key Management Page

Add to request header:

Authorization: Bearer YOUR_API_KEY

Body

modelstringbodyrequireddefault: doubao-seedream-5-5

Image generation model name

Example: "doubao-seedream-5-5"

promptstringbody

Text description, required for ordinary generation and editing. With layer_decomposition enabled, omit it to let the model identify elements automatically.

sizestringbodydefault: 2K

Accepts 1K, 1.5K, 2K, or explicit WIDTHxHEIGHT pixels, such as 2048x2048. Presets select a resolution tier rather than a fixed aspect ratio. Explicit dimensions must have 921600-4624220 total pixels. For a fixed square, use 2048x2048 rather than 1:1. Ordinary generation defaults to 2K; explicitly use 2K for layer decomposition.

image_urlsstring[]body

Reference image URLs for image editing or multiple-image references.

Up to 10 reference images.
Use publicly accessible HTTP/HTTPS URLs; inline base64 data is not supported.
Upload local images through the image upload API first.
The reference_images and images array fields are also supported.

imagestringbody

A URL string for one reference image. For multiple images, use image_urls; do not put an array in image.

layer_decompositionbooleanbody

Set true to decompose exactly one reference image. You may omit prompt; omit sequential generation parameters. Results include a base image and transparent PNG layers with z_index, placement information, and names. The current API handles at most 1 base image plus 16 layers. Layer count and OCR settings are not exposed.

optimize_prompt_optionsobjectbody

Prompt optimization options. Use {"mode": "standard"}. Seedream 5.5 rejects fast.

metadataobjectbody

Channel-specific parameters for advanced Seedream 5.5 model configuration

metadata properties

metadata.output_formatstringbodydefault: png

Output format: png or jpeg. Use png for a transparent background.

metadata.backgroundstringbody

Accepts opaque or transparent. A transparent background cannot be combined with output_format=jpeg. With transparent and no format, PNG is selected. The current API does not accept an explicit auto value.

metadata.watermarkbooleanbodydefault: false

Controls the visible AI generated watermark. Set false to disable it or true to enable it. This does not imply removal of provenance metadata or invisible markers.

metadata.response_formatstringbodydefault: url

This page uses url mode. Retrieve image URLs from the asynchronous task result.

Parameter limitations

Ordinary multi-image generation is not supported. Omit sequential_image_generation and sequential_image_generation_options; even disabled is rejected upstream. stream=true is not supported; omit stream or use false. The current API does not support tools web-search parameters or seed.

Query the task

A successful submission does not mean generation is complete. Query with the same API Key. Status may be pending, queued, in_progress, completed, or failed. Read result.data on completion, or error on failure.

curl "https://toapis.com/v1/images/generations/TASK_ID" \
  -H "Authorization: Bearer $TOAPIS_API_KEY"

Response

idstring

Unique task identifier for status queries

objectstring

Object type, always generation.task

modelstring

Model name used

statusstring

Task status

queued - Queued for processing
in_progress - Processing
completed - Successfully completed
failed - Failed

progressinteger

Task progress percentage (0-100)

created_atinteger

Task creation timestamp (Unix timestamp)

metadataobject

Task metadata

result.dataarray

Completed image list: one item for ordinary generation, multiple items for layer decomposition.

result.data[]object

Image URL, actual pixel dimensions, and output format.

result.data[].z_indexinteger

Layer stacking order. 0 is the base image; other layers may also include bounding_box, name, and description.

Set the TOAPIS_API_KEY environment variable before running these examples. Replace the example.com reference placeholders with accessible image URLs.

requestExample

curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedream-5-5",
  "prompt": "A red toy sailboat and a small yellow sun, isolated objects, no text.",
  "size": "2K",
  "metadata": {
    "output_format": "png",
    "background": "transparent",
    "watermark": false,
    "response_format": "url"
  }
}'

curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedream-5-5",
  "prompt": "Combine the subjects from both references into one product illustration.",
  "size": "2K",
  "image_urls": [
    "https://example.com/reference-front.png",
    "https://example.com/reference-side.jpg"
  ],
  "metadata": {
    "output_format": "png",
    "watermark": false,
    "response_format": "url"
  }
}'

curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedream-5-5",
  "image": "https://example.com/composition.png",
  "layer_decomposition": true,
  "size": "2K",
  "metadata": {
    "output_format": "png",
    "watermark": false,
    "response_format": "url"
  }
}'

responseExample

{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "doubao-seedream-5-5",
  "status": "pending",
  "progress": 0,
  "created_at": 1794300000,
  "metadata": {}
}

{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "doubao-seedream-5-5",
  "status": "completed",
  "progress": 100,
  "created_at": 1794300000,
  "metadata": {},
  "result": {
    "type": "image",
    "data": [
      {
        "url": "https://files.toapis.com/images/example/seedream-5-5.png",
        "size": "2512x1680",
        "output_format": "png"
      }
    ]
  }
}