Skip to content

MaaS_Seedream API

Request Protocol

Http

Parameter Name Type Description
authorization string Authentication

Image Generation

Request URL

https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/seedream/image/generations

Request Method

POST

Request Parameters

Attribute Name Type Required Description
prompt string Yes Prompt for image generation, supporting Chinese and English. It is recommended not to exceed 300 Chinese characters or 600 English words. Excessively long text may disperse information, causing the model to ignore details and focus only on key points, resulting in missing elements in the generated image.
image string/array No Input image information, supporting URL or Base64 encoding. Single or multiple images are supported. MaaS_Seedream_4.5 and MaaS_Seedream_4.0 support single or multiple images, while MaaS_SeedEdit_3.0_i2i only supports single image input.
  • Image URL: Ensure the image URL is accessible.
  • Base64 encoding: Follow the format data:image/<image format>;base64,<Base64 encoded string>. Note that <image format> must be in lowercase, e.g., data:image/png;base64,<base64_image>
Notes:

  • Uploaded images must meet the following requirements:

    • Image format: jpeg, png (MaaS_Seedream_4.5 and MaaS_Seedream_4.0 additionally support webp, bmp, tiff, gif formats)

    • Aspect ratio (width/height) range:

      • [1/16, 16] (Applicable models: MaaS_Seedream_4.5, MaaS_Seedream_4.0)​
      • [1/3, 3] (Applicable models: MaaS_SeedEdit_3.0_i2i, MaaS_SeedEdit_3.0_t2i)

    • Width and height (px) > 14

    • Size: No more than 10MB

    • Total pixels: No more than 6000×6000 px

  • A maximum of 14 reference images can be uploaded.
size string No Specify the size of the generated image. Two methods are supported and cannot be mixed.

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

    • Optional values: 2K, 4K

  • Method 2 | Specify the width and height in pixels of the generated image. Common recommended values are shown in the attached table:

    • Default value: 2048x2048
    • Total pixel range: [2560x1440=3686400, 4096x4096=16777216]
    • Aspect ratio range: [1/16, 16]
Note: When using Method 2, both the total pixel range and aspect ratio range must be satisfied. The total pixel limit applies to the product of width and height in pixels, not to the individual values of width or height. MaaS_SeedEdit_3.0_i2i currently only supports "adaptive".
  • adaptive: Compare the size of your input image with the sizes in Attached Table 2, and select the closest one as the size of the output image. Specifically, the first ratio with the smallest difference from the original image's aspect ratio will be selected in order from the optional ratios as the ratio of the generated image.
seed integer No Random number seed to control the randomness of the model's generated content
  • Default value: -1.
  • Value range: [-1, 2147483647].
Only MaaS_SeedEdit_3.0_i2i supports this parameter
sequential_image_generation string No Control whether to disable the batch image generation function. Default value: disabled
  • auto: Auto-judgment mode. The model will independently determine whether to return batch images and the number of images in the batch based on the prompt provided by the user.
  • disabled: Disable the batch image generation function. The model will only generate one image.
MaaS_SeedEdit_3.0_i2i does not support this parameter
sequential_image_generation_options object No Configuration for the batch image generation function. Only takes effect when sequential_image_generation is set to "auto".
sequential_image_generation_options.max_images integer No Specify the maximum number of images that can be generated for this request. Default value: 15.
  • Value range: [1, 15]
Note: The actual number of images that can be generated is affected by both max_images and the number of input reference images. The number of input reference images + the number of finally generated images ≤ 15.
stream boolean No Default value: false. Control whether to enable streaming output mode.
  • false: Non-streaming output mode. Wait for all images to be generated before returning all information at once.
  • true: Streaming output mode. Return the result of each image generation in real time. Streaming output mode takes effect in both single-image and batch-image generation scenarios.
MaaS_SeedEdit_3.0_i2i does not support this parameter
guidance_scale float No Default value for MaaS_SeedEdit_3.0_i2i: 5.5. MaaS_Seedream_4.5 and MaaS_Seedream_4.0 do not support this parameter. It represents the degree of consistency between the model's output result and the prompt, and the degree of freedom of the generated image (also known as text weight). The larger the value, the smaller the model's 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. Default value: url. Generated images are in jpeg format, supporting the following two return methods:
  • url: Return the image download link; The link is valid for 24 hours after the image is generated. Please download the image in a timely manner.
  • b64_json: Return image data in JSON format as a Base64 encoded string.
watermark boolean No Whether to add a watermark to the generated image. Default value: true.
  • false: Do not add a watermark.
  • true: Add a watermark with the text "AI Generated" in the bottom right corner of the image
optimize_prompt_options object No Configuration for the prompt optimization function. MaaS_SeedEdit_3.0_i2i does not support this parameter
optimize_prompt_options.mode string No Set the mode for the prompt optimization function. Default value: standard.
  • standard: Standard mode. Higher quality of generated content, but longer time-consuming.
  • fast: Fast mode. Shorter time-consuming for generated content, but average quality.
  • Attached Table 1: Recommended Width and Height Pixels for MaaS_Seedream_4.5
Aspect Ratio Width x Height (px)
1:1 2048x2048
4:3 2304x1728
3:4 1728x2304
16:9 2560x1440
9:16 1440x2560
3:2 2496x1664
2:3 1664x2496
21:9 3024x1296
  • Attached Table 2: Preset Width and Height Values for MaaS_SeedEdit_3.0_i2i
Width/Height Width (px) Height (px)
0.33 512 1536
0.35 544 1536
0.38 576 1536
0.4 608 1536
0.42 640 1536
0.47 640 1376
0.51 672 1312
0.55 704 1280
0.56 736 1312
0.6 768 1280
0.63 768 1216
0.66 800 1216
0.67 832 1248
0.7 832 1184
0.72 832 1152
0.75 864 1152
0.78 896 1152
0.82 896 1088
0.85 928 1088
0.88 960 1088
0.91 992 1088
0.94 1024 1088
0.97 1024 1056
1 1024 1024
1.06 1056 992
1.1 1088 992
1.17 1120 960
1.24 1152 928
1.29 1152 896
1.33 1152 864
1.42 1184 832
1.46 1216 832
1.5 1248 832
1.56 1248 800
1.62 1248 768
1.67 1280 768
1.74 1280 736
1.82 1280 704
1.78 1312 736
1.86 1312 704
1.95 1312 672
2 1344 672
2.05 1376 672
2.1 1408 672
2.2 1408 640
2.25 1440 640
2.3 1472 640
2.35 1504 640
2.4 1536 640
2.53 1536 608
2.67 1536 576
2.82 1536 544
3 1536 512

Request Body Examples

Text-to-Image

curl https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/seedream/image/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "A dynamic close-up editorial portrait of a model with sharp eyes, wearing a sculptural hat, rich color blocking, sharp focus on the eyes, shallow depth of field, with the aesthetic style of a Vogue magazine cover, shot with a medium format camera, and strong studio lighting effects.",
    "size": "2K",
    "watermark": false
}'

Image-to-Image

curl -X https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/seedream/image/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "Keep the model's pose and the flowing shape of the liquid clothing unchanged. Change the clothing material from silver metal to completely transparent clear water (or glass). Through the flowing liquid water, the model's skin details 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
}'

Multiple-Image-to-Image

curl -X https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/seedream/image/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "Change the clothing in Image 1 to 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
}'

Response Examples

Non-Streaming Response Example

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

Streaming Response Example

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]

Streaming Response Event Description

Event Type Description
image_generation.partial_succeeded Returned when any image is successfully generated in streaming response mode
image_generation.partial_failed Returned when any image generation fails in streaming response mode.
  • If the failure reason is review rejection: The next image generation task will still continue, i.e., it will not affect the generation process of other images in the same request.
  • If the failure reason is internal service exception (500): The next image generation task will not continue.
image_generation.completed Returned after all images of the request (whether successful or failed) have been processed, and it is the last response event of the streaming return

Error Response Example

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