Seedream

​

1. Overview

​

Supported Models

​

2. Endpoint and Authentication

POST https://{api_domain}/v3/bytedance/api/v3/images/generations

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

​

3. Request Parameters

​

3.1 Common Parameters

​

3.2 Model-Specific Parameters

​

3.3 Text-to-Image Example

curl -sS -X POST "https://{api_domain}/v3/bytedance/api/v3/images/generations" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "一只戴着红色围巾的金毛犬，在雪山湖边的自然光下，电影感摄影",
    "size": "2K",
    "response_format": "url",
    "output_format": "jpeg",
    "watermark": true
  }'

​

3.4 Image-to-Image Example

{
  "model": "seedream-4-5-251128",
  "prompt": "将参考图中的人物和服装放在统一的城市夜景中，保持人物特征一致",
  "image": [
    "https://example.com/person.png",
    "https://example.com/outfit.png"
  ],
  "size": "2560x1440",
  "response_format": "url"
}

​

3.5 Multi-Image Group Example (4.0, 4.5, and 5.0 Lite only)

{
  "model": "seedream-5-0-260128",
  "prompt": "生成三张风格统一的四季海报",
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": {
    "max_images": 3
  },
  "response_format": "url"
}

​

4. Response

{
  "created": 1786000000,
  "model": "seedream-4-5-251128",
  "data": [
    {
      "url": "https://example.com/generated-image.jpeg",
      "size": "2560x1440",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "generated_images": 1,
    "input_images": 0
  }
}

• When response_format=url, data[].url is returned; when response_format=b64_json, data[].b64_json is returned.
• Seedream 4.0, 4.5, and 5.0 Lite can return multiple data items in multi-image group mode.
• Seedream 5.0 Pro returns a single data item in the image generation scenario; when layer decomposition is enabled, it returns multiple data items (one base image + multiple layers), each additionally containing the layer stacking order z_index (0 for the base image), the name name, the description description, and the bounding box bounding_box (with absolute / normalized coordinates; the base image does not return this field).
• model returns the client model ID used for this request.
• The validity period of image URLs is determined by the platform and upstream services; download and save the images promptly after receiving the response.

​

5. Model Limitations

​

Seedream 4.0 / 4.5 / 5.0 Lite

• Supports text-to-image, image-to-image, and multi-image group generation.
• Multi-image groups use sequential_image_generation and its options field.
• For the number of input images, image size, resolution, and aspect ratio, refer to the upstream documentation of the corresponding model. Seedream 4.0 and 4.5 always output JPEG and do not support the request parameter output_format; Seedream 5.0 Lite supports jpeg and png.

​

Seedream 5.0 Pro

• Supports text-to-image, image-to-image from a single image, and multi-image fusion.
• In the image generation scenario, it returns one successful image. When layer decomposition (layer_decomposition: true) is enabled, it returns one base image and multiple layers (up to 16 layers), in which case data contains multiple items. Multi-image group generation (sequential_image_generation) is not supported.
• Does not support sequential_image_generation or sequential_image_generation_options.
• size can be 1K, 1.5K, 2K, or an explicit widthxheight.
• When explicit width and height are given, the aspect ratio and total pixel count must satisfy the model limitations; the actual dimensions of the output image are determined by data[].size in the response.
• Supports layer decomposition: when layer_decomposition: true is set, a single input image is decomposed into one base image and up to 16 independently editable layers (each layer is a PNG with an alpha channel). In this scenario, image is required and only one image can be passed; passing multiple images results in an error. Layer decomposition is all-or-nothing: if any layer fails, the entire request fails; partial success is not supported.
• size rules for layer decomposition: the base image resolution equals size; each layer’s resolution is close to size, but each layer maintains the aspect ratio of its corresponding region in the original image, so the actual pixel counts of the layers differ. This means output images from the same request may fall into different pixel-based pricing tiers. size can be 1K, 1.5K, 2K, or auto, and defaults to auto.

​

6. Billing and Usage

• 4.0, 4.5, and 5.0 Lite are billed by the number of successfully generated images; for multi-image group generation, billing is based on the actual number of successful outputs.
• 5.0 Pro is billed by successfully output images; with multi-image input, the first reference image is free and additional reference images are metered separately; different output sizes correspond to different pricing tiers. When layer decomposition is enabled, the base image and each layer each count as one successful output image, and each is billed separately according to the pricing tier its data[].size pixel count falls into (for example, the base image may be in a high-pixel tier while some layers are in lower-pixel tiers); the final bill is the sum of the quantities across all tiers.
• The usage unit is image or item.
• For exact pricing, refer to the product pricing page of your platform.

​

7. Troubleshooting