Skip to content

MaaS-Seedream

Capability List

Model ID Capability Support Rate limit (max. IPM sheets/minute)
doubao-seedream-5-0-pro-260628 Single Image Generation: Text-to-Image, Single Image-to-Image, Multi-reference Image-to-Image 500
doubao-seedream-5-0-260128 (also compatible with: doubao-seedream-5-0-lite-260128) Single-image generation: text-to-image, single image-to-image, multi-reference image-to-image Group-image generation: text-to-image group, single image-to-image group, multi-reference image-to-image group 500
doubao-seedream-4-5-251128 Single-image generation: text-to-image, single image-to-image, multi-reference image-to-image Group-image generation: text-to-image group, single image-to-image group, multi-reference image-to-image group 500
doubao-seedream-4-0-250828 Single-image generation: text-to-image, single image-to-image, multi-reference image-to-image Group-image generation: text-to-image group, single image-to-image group, multi-reference image-to-image group 500

Instructions for Layer Split Mode

  • Only a single image to be split can be input; an error will be reported if multiple images are passed in.

  • If any layer fails to be generated, the entire request will report an error, and partial success is not supported.

  • If the number of splits required by the prompt exceeds the upper limit, some layer information may be lost.

  • In the response structure data, the position and content information of each output layer will be returned, including the layer order (z_index), bounding box information (bounding_box), name (name) and description (description).

Interfaces and Request Parameters

Image Generation API

POST

https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/seedream/image/generations

Request Parameters

Attribute Name Type Required or not Description
prompt string
 Yes Prompts for image generation, supporting both Chinese and English, are recommended to be no longer than 300 Chinese characters or 600 English words. Excessively long prompts tend to scatter information, which may lead the model to ignore details and only focus on key points, resulting in missing elements in the generated image.
image
 string/array
 No
 The input image information supports URL or Base64 encoding. Among them, seedream-5.0-lite/5.0-pro/4.5/4.0 support single-image or multi-image input.
(If the total size of the image exceeds 10MB, it is recommended to transmit it via URL.)
  • Image URL: Please ensure that the image URL is accessible.
  • Base64 Encoding: Please follow the format data: image/<image_format>;base64,<Base64_encoded_content>. Note that <image_format> must be in lowercase, for example: data: image/png;base64,<base64_image>
Image Generation Scenarios:

  • The incoming image needs to meet the following requirements:

    • Image formats: jpeg, png (seedream-5.0-lite/4.5/4.0 models add support for webp, bmp, tiff, gif formats)

    • Aspect Ratio (Width/Height) Range:

      • [1/16,16](Applicable models: seedream-5.0-lite/4.5/4.0)

    • Width and height (px) > 14

    • Size: No more than 30MB

    • Total pixels: No more than 6000x6000 = 36,000,000 px (this is a limit on the product of the width and height in pixels for a single image, rather than a limit on the individual values of width or height)

    • seedream-5.0-lite/4.5/4.0 supports a maximum of 14 reference images as input.

    • Seedream 5.0 Pro supports up to 10 reference images as input.

Layer Splitting Scenarios:
When the layer decomposition mode is enabled (i. e., the value of layer_decomposition is true), the image parameter is mandatory, and only a single image is supported as input (an error will be thrown if multiple images are passed).
Requirements for single image upload:
  • Image formats: png, jpeg
  • Aspect Ratio: [1/16,16]
  • Size: No more than 30MB
  • Total pixel (width × height) range: [512×512 (262144), 6000×6000 (36 million)](This is a restriction on the product of the width and height in pixels of a single image, not a restriction on the individual values of width or height)
layer_decomposition
 boolean No Controls whether to enable the layer splitting function. The default value is false
Layer splitting automatically decomposes elements such as the subject, background, and text of a single image into 1 base map and up to 16 independently editable layers. Each layer is a PNG image with an alpha channel.
  • true: Layer splitting mode. The model decomposes the input image into a base map and multiple layers.
  • false: Image generation mode, no layer splitting will be performed.
  • Only seedream-5.0-pro is supported
size
 string
 No
 Specify the size information of the generated image. The following two methods are supported and cannot be mixed.

  • Method 1 | Specify the resolution of the generated image, and describe the aspect ratio, shape or intended use of the image in natural language in the prompt; the model will ultimately determine the size of the generated image.

    • Optional values: seedream-5.0-pro (1K, 1.5K, 2K; 2K by default. 1.5K is priced the same as 1K but delivers better image generation results), seedream-5.0-lite (2K, 3K, 4K), doubao-seedream-4.5 (2K, 4K), doubao-seedream-4.0 (1K, 2K, 4K)

  • Mode 2 | Specify the width and height pixel values of the generated image. See the attached table for common recommended values:

    • Default value:(2048x2048)
    • 总像素取值范围：seedream-5.0-pro([1280x720（921600）, 2048x2048x1.1025（4624220）])、seedream-5.0-lite（[2560x1440=3686400, 3072x3072x1.1025=10404496] ）、seedream-4.5（[2560x1440=3686400, 4096x4096=16777216] ）、seedream-4.0（[1280x720=921600, 4096x4096=16777216] ）
    • Aspect ratio value range: [1/16,16]
Note: When Mode 2 is adopted, both the total pixel value range and the aspect ratio value range shall be satisfied simultaneously. The total pixel here refers to the restriction on the product of the width and height in pixels, rather than a restriction on the individual value of either the width or the height.

In the layer splitting scenario (seedream-5.0-pro)
It can only be set by specifying the resolution level. The resolution rules for the output image are as follows:
  • Base map: The resolution of the output base map is consistent with the resolution specified by size; the aspect ratio of the output base map is consistent with that of the original image to be split.
  • Each layer: The resolution of the output layer is close to the resolution specified by size; each output layer has the same aspect ratio as its corresponding layer in the original image.
Default and optional values for size:
  • Default value: auto
  • Optional values: 1K, 1.5K, 2K, auto (the output will be generated based on the size and aspect ratio of the input image)
auto adaptation rules
In auto mode, the model will generate output based on the original dimensions of the base image and each layer in the input image:
  • If the original dimensions of the base map and each layer in the input image fall within the range [1280x720 (921600), 2048x2048x1.1025 (4624220)], output the base map and each layer at their original dimensions while maintaining their respective aspect ratios from the original image.
  • If the original dimensions of the base map and each layer in the input image are smaller than 1K, output the base map and each layer at 1K, and each shall maintain its aspect ratio in the original image.
  • If the original dimensions of the base map and each layer in the input image are larger than 2K, output the base map and each layer at 2K resolution while respectively maintaining their aspect ratios as in the original image.
seed integer No Default value: -1. This parameter is only supported by seededit-3.0-i2i. It refers to a random seed, which is used to control the randomness of the content generated by the model. The value ranges from [-1,2147483647].
sequential_image_generation
string
 No This parameter is only supported by seedream-5.0-lite, 4.5 and 4.0
Seedream 5.0 Pro is not supported
Controls whether to disable the gallery function, with the default value being disabled
  • auto: Automatic judgment mode, in which the model will independently determine whether to return a group of images and the number of images contained in the group based on the prompts provided by the user.
  • disabled: Disable the image gallery function, and the model will only generate one image.
sequential_image_generation_options
 object No This parameter and the configuration of the image group feature are only supported by seedream-5.0-lite/4.5/4.0, and will only take effect when sequential_image_generation is set to auto.
Seedream 5.0 Pro is not supported
sequential_image_generation_options.max_images
 integer
 No
 Specify the maximum number of images that can be generated for this request; the default value is 15.
  • Value range: [1,15]
Note:
The actual number of images that can be generated is not only affected by max_images, but also by the number of input reference images. The total number of input reference images plus the number of finally generated images shall not exceed 15.
stream boolean No This parameter is only supported by seedream-5.0-lite, 4.5 and 4.0
The default value is false, which controls whether to enable the streaming output mode.
  • false: Non-streaming output mode, which waits until all images are fully generated before returning all information at once.
  • true: Streaming output mode, which returns the output result of each image in real time. This mode takes effect in both single-image and batch-image generation scenarios.
tools Array No Only seedream-5.0-lite supports this parameter
tools.type string
 No Only seedream-5.0-lite supports this parameter
  • web_search (the only currently available value)
guidance_scale
 float
 No
 seedream-3.0-t2i default value 2.5
seededit-3.0-i2i default value 5.5
seedream-5.0-lite/4.5/4.0 not supported
The degree of consistency between the model output and the prompt, as well as the degree of freedom of the generated image, is also known as text weight; the larger the value, the smaller the model's degree of freedom, and the stronger the correlation with the user's input prompt.
Value range: [1,10].
response_format
string No Specify the return format of the generated image; the default value is url.
The generated image is in JPEG format and supports the following two return methods:
  • url: returns the image download link;the link is valid within 24 hours after the image is generated, please download the image in time.
  • b64_json: Returns image data in JSON format as a Base64-encoded string.
watermark
boolean No Specifies whether to add a watermark to the generated image; the default value is true.
  • false: Do not add a watermark.
  • true: Add a watermark label reading "AI-generated" at the bottom right corner of the image
output_format string
 No Only seedream-5.0-lite/5.0 pro supports this parameter
  • jpeg (default)
  • png
background
 string No Used to control whether to generate images with an alpha channel. The default value is opaque, and the optional values are as follows:
  • transparent: Transparent background mode, which outputs images with a transparent background.
  • opaque: Opaque background mode, which generates a regular solid background image.
Restrictions on Use
  • Only the image-to-image scenario is supported, and only the input of 1 image with an alpha channel is supported;
  • In transparent background mode, the output image defaults to PNG format; if output_format is simultaneously configured as JPEG, an error will be triggered.
  • If a file format that does not support an alpha channel (such as JPEG) is passed in, an error will be triggered.
Only seedream-5.0-pro is supported
optimize_prompt_options object
 No Configuration of the Prompt Optimization Function
seededit-3.0-i2i does not support this parameter
optimize_prompt_options.mode
 string
 No Set the mode used by the prompt optimization function; the default value is standard.
  • standard: Standard mode, which generates higher-quality content but takes longer time.
  • fast: Fast mode, which takes less time to generate content but delivers average quality. Not supported by seedream-5.0-lite/4.5
  • Appendix 1: Recommended width and height pixel values for seedream4.5
aspect ratio width and height pixel values
1:1 2048x2048
4:3 2304x1728
3:4 1728x2304
16:9 2560x1440
9:16 1440x2560
3:2 2496x1664
2:3 1664x2496
21:9 3024x1296

Appendix 2: seedream4.0

resolution aspect ratio width and height pixel values
1k 1:1 1024x1024
4:3 1152x864
3:4 864x1152
16:9 1280x720
9:16 720x1280
3:2 1248x832
2:3 832x1248
21:9 1512x648
2k 1:1 2048x2048
4:3 2304x1728
3:4 1728x2304
16:9 2848x1600
9:16 1600x2848
3:2 2496x1664
2:3 1664x2496
21:9 3136x1344
4k 1:1 4096x4096
4:3 4704x3520
3:4 3520x4704
16:9 5504x3040
9:16 3040x5504
3:2 4992x3328
2:3 3328x4992
21:9 6240x2656
  • Appendix 3: seedream5.0 lite
resolution aspect ratio width and height pixel values
2k 1:1 2048x2048
4:3 2304x1728
3:4 1728x2304
16:9 2848x1600
9:16 1600x2848
3:2 2496x1664
2:3 1664x2496
21:9 3136x1344
3k 1:1 3072x3072
4:3 3456x2592
3:4 2592x3456
16:9 4096x2304
9:16 2304x4096
3:2 3744x2496
2:3 2496x3744
21:9 4704x2016
4k 1:1 4096x4096
4:3 4704x3520
3:4 3520x4704
16:9 5504x3040
9:16 3040x5504
3:2 4992x3328
2:3 3328x4992
21:9 6240x2656
  • Appendix 4: Recommended Aspect Ratio Pixel Values for seedream5.0 pro
resolution aspect ratio width and height pixel values
1k 1:1 1024x1024
4:3 1152x864
3:4 864x1152
16:9 1424x800
9:16 800x1424
3:2 1248x832
2:3 832x1248
21:9 1568x672
1.5K 1:1 1536x1536
4:3 1792x1344
3:4 1344x1792
16:9 2048x1152
9:16 1152x2048
3:2 1872x1248
2:3 1248x1872
21:9 2352x1008
2k 1:1 2048x2048
4:3 2368x1776
3:4 1776x2368
16:9 2816x1584
9:16 1584x2816
3:2 2496x1664
2:3 1664x2496
21:9 3136x1344

Request Body Example

Text-to-Image

curl https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/seedream/image/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "prompt": "A vibrant close-up editorial portrait, the model has a sharp gaze, wearing a sculptural hat, rich color blocking, sharp eye focus, shallow depth of field, Vogue magazine cover aesthetic style, shot in medium format, with intense studio lighting.",
    "size": "2K",
    "watermark": false
}'

Image-to-Image

curl -X https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/seedream/image/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${your_AK}" \
  -d '{
    "prompt": "Keep the model pose and the flowing shape of the liquid garment unchanged. Change the garment material from silver metal to completely transparent clear water (or glass). Through the liquid water flow, the skin details of the model can be seen. The light and shadow change from reflection to refraction.",
    "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png",
    "size": "2K",
    "watermark": false
}'

Multi-Image to Image

curl -X https://genaiapi-m2.cloudsway.net/v1/ai/{endpointPath}/seedream/image/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${your_AK}" \
  -d '{
    "prompt": "Replace the clothing in image 1 with the clothing in image 2",
    "image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_1.png", "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imagesToimage_2.png"],
    "sequential_image_generation": "disabled",
    "size": "2K",
    "watermark": false
}'

Example of Non-Streaming Response

{
    "model": "doubao-seedream-4-5-251128",
    "created": 1757323224,
    "data": [
        {
            "url": "https://...",
            "output_format": "jpeg",
            "size": "1760x2368"
        }
    ],
    "usage": {
        "generated_images": 1,
        "output_tokens": 16280,
        "input_images": 3,
        "total_tokens": 16280
    }
}

Example of Streaming Response

event: image_generation.partial_succeeded
data: {
  "type": "image_generation.partial_succeeded",
  "model": "doubao-seedream-4-5-251128",
  "created": 1757396757,
  "image_index": 0,
  "url": "https://...",
  "size": "2496x1664"
}

event: image_generation.partial_succeeded
data: {
  "type": "image_generation.partial_succeeded",
  "model": "doubao-seedream-4-5-251128",
  "created": 1757396785,
  "image_index": 1,
  "url": "https://...",
  "size": "2496x1664"
}

event: image_generation.partial_succeeded
data: {
  "type": "image_generation.partial_succeeded",
  "model": "doubao-seedream-4-5-251128",
  "created": 1757396825,
  "image_index": 2,
  "url": "https://...",
  "size": "2496x1664"
}

event: image_generation.completed
data: {
  "type": "image_generation.completed",
  "model": "doubao-seedream-4-5-251128",
  "created": 1757396825,
  "usage": {
    "generated_images": 3,
    "output_tokens": 48672,
    "total_tokens": 48672
  }
}

data: [DONE]

Description of Streaming Response Events

Event Type Description
image_generation.partial_succeeded In streaming response mode, this event is returned when any image is successfully generated
image_generation.partial_failed
 In the streaming response mode, this event is returned when any image fails to be generated.
  • If the failure is caused by failed review, the system will still proceed to request the next image generation task, which means it will not affect the generation process of other images within the same request.
  • If the failure is caused by an internal service exception (500), the system will not proceed to request the next image generation task.
image_generation.completed It is the last response event of this streaming return, which is returned after all requested images (whether successful or failed) have been processed.

Response Example When an Error Occurs

"error": {
  "code":"BadRequest"，
  "message":"The request failed because it is missing one or multiple required parameters. Request ID: {id}"
}