MaaS_Seedream API

Request Protocol

http

Request URL

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

Request Method

POST

Request Parameters

Parameter Name	Type	Is it required?	Description
prompt	string	is	The prompt used to generate images supports both Chinese and English, and it is recommended not to exceed 300 Chinese characters or 600 English words. Excessive text can easily cause information to be scattered, and the model may thus overlook details and only focus on key points, resulting in missing elements in the image.
image	string/array	No	The input image information supports URL or Base64 encoding. Among them, MaaS_Seedream_5.0_lite/4.5/4.0 supports single-image or multi-image input, while seededit-3.0-i2i only supports single-image input Image URL: Please ensure that the image URL is accessible. Base64 Encoding: Please follow this format data:image/<image format>;base64,<Base64 encoding>. Note that <image format> should be in lowercase, e.g., data:image/png;base64,<base64_image> Note: The input image needs to meet the following conditions: Image formats: jpeg, png (MaaS_Seedream_5.0_lite/4.5/4.0 models newly support webp, bmp, tiff, gif formats) Aspect ratio (width/height) range: [1/16, 16] (Applicable models: MaaS_Seedream_5.0_lite/4.5/4.0) [1/3, 3] (Applicable models: seedream-3.0-t2i, seededit-3.0-i2i) Width, height, and length (px) > 14 Size: no more than 10MB Total pixels: no more than 6000x6000 = 36000000 px (this is a limit on the product of the pixel width and height of a single image, rather than a limit on the individual values of width or height) MaaS_Seedream_5.0_lite/4.5/4.0 supports up to 14 reference images.
size	string	No	Specify the size information of the generated image, supporting the following two methods, which cannot be mixed. Method 1 \| Specify the resolution of the generated image, and describe the aspect ratio, shape, or purpose of the image in natural language within the prompt, with the final determination of the image size made by the model. Optional values：MaaS_Seedream_5.0_lite（2K、3K）、doubao-seedream-4.5（2K、4K）、doubao-seedream-4.0（1K、2K、4K） Method 2 \| Specify the width and height pixel values of the generated image. See the attached table for common recommended values: Default value: 2048x2048 Total pixel value range：MaaS_Seedream_5.0_lite（[2560x1440=3686400, 3072x3072x1.1025=10404496] ）、doubao-seedream-4.5（[2560x1440=3686400, 4096x4096=16777216] ）、doubao-seedream-4.0（[1280x720=921600, 4096x4096=16777216] ） Aspect ratio range: [1/16, 16] Note: When using Method 2, both the total pixel value range and the aspect ratio value range must be met simultaneously. Here, the total pixels refer to the limit on the product of the width and height pixels, rather than the individual values of the width or height.
seed	integer	No	Default value -1, only supported by seededit-3.0-i2i, a random number seed used to control the randomness of the content generated by the model. The value range is [-1, 2147483647].
sequential_image_generation	string	No	Only MaaS_Seedream_5.0_lite /4.5/4.0 support this parameter Controls whether to turn off the group image function, with the default value being disabled auto: Automatic judgment mode, where the model will independently determine whether to return a group of images and the number of images included in the group based on the prompt provided by the user. disabled: Turn off the group image function, and the model will only generate one image.
sequential_image_generation_options	object	No	Only MaaS_Seedream_5.0_lite /4.5/4.0 support the configuration of this parameter and the group image feature. It only takes effect when sequential_image_generation is set to auto.
sequential_image_generation_options.max_images	integer	No	Specifies the maximum number of images that can be generated for this request, with a default value of 15. Value range: [1, 15] Note: The actual number of images that can be generated, in addition to being affected by max_images , is also affected by the number of input reference images. The number of input reference images + the number of finally generated images ≤ 15.
stream	boolean	No	Only MaaS_Seedream_5.0_lite /4.5/4.0 supports this parameter The default value is false, which controls whether to enable the streaming output mode. false: Non-streaming output mode, waiting for all images to finish generating before returning all information at once. true: Streaming output mode, which immediately returns the output results of each image. The streaming output mode is effective in both single-image and multi-image generation scenarios.
tools	Array	No	Only MaaS_Seedream_5.0_lite supports this parameter
type	string	No	Only MaaS_Seedream_5.0_lite supports this parameter web_search (currently the only available value)
guidance_scale	float	No	MaaS-seedream-3.0-t2i default value 2.5 MaaS-seededit-3.0-i2i default value 5.5 MaaS_Seedream_5.0_lite/4.5/4.0 not supported The consistency between the model output and the prompt, the degree of freedom in generating images, 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 input prompt. Value range: [1, 10].
response_format	string	No	Specify the return format of the generated image, with the default value being url. The generated images are in JPEG format and support the following two return methods: url: Returns 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: Returns image data in JSON format as a Base64-encoded string.
watermark	boolean	No	Whether to add a watermark to the generated image, with a default value of true. false: Do not add watermark. true: Add a watermark with the words "AI Generated" in the bottom right corner of the image
output_format	string	No	Only MaaS_Seedream_5.0_lite supports this parameter jpeg (default) png
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 feature, with the default value being standard. standard: Standard mode, which produces higher-quality content but takes longer. fast: Fast mode, which takes less time to generate content but has average quality.MaaS_Seedream_5.0_lite/4.5 not supported

Request Body Example

Text-to-Image

Example of Curl Request

curl https://genaiapi.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 of a model with a piercing gaze, wearing a sculptural hat, featuring rich color blocking, sharp focus on the eyes, shallow depth of field, embodying the aesthetic of a Vogue magazine cover, shot on medium format with dramatic studio lighting.。",
    "size": "2K",
    "watermark": false
}'

Python Request Example

import requests
import os

# API configuration
api_key = os.environ.get("API_KEY", "your-api-key-here")  # Recommended to get from environment variable
endpoint_path = "your-endpoint-path"  # Please replace with actual path
url = f"https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/seedream/image/generations"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer $API_KEY"
}

payload = {
    "prompt": "A vibrant close-up editorial portrait of a model with a piercing gaze, wearing a sculptural hat, featuring rich color blocking, sharp focus on the eyes, shallow depth of field, embodying the aesthetic of a Vogue magazine cover, shot on medium format with dramatic studio lighting.",
    "size": "2K",
    "watermark": False
}

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()  # Check if request was successful
    result = response.json()
    print("Generation successful!")
    print(result)
except requests.exceptions.RequestException as e:
    print(f"Request error: {e}")
    if hasattr(e, 'response') and e.response is not None:
        print(f"Response content: {e.response.text}")

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "images": [
      {
        "url": "https://genaiapi.cloudsway.net/static/images/generated/seedream_20260327_123456_abc123.jpg",
        "width": 2560,
        "height": 1440,
        "size": "2K",
        "format": "jpg"
      }
    ],
    "parameters": {
      "prompt": "...",
      "size": "2K",
      "watermark": false,
      "model": "seedream",
      "endpoint": "image/generations"
    },
    "usage": {
      "total_tokens": 85,
      "image_count": 1
    },
    "created_at": "2026-03-27T10:30:45Z",
    "request_id": "req_abc123def456"
  }
}

Image-to-Image

Example of Curl Request

curl -X https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/seedream/image/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "prompt": "A model in the same pose, wearing a liquid dress made of clear water (or glass), maintaining the fluid shape of the garment. The transparent water flows over the skin, revealing detailed skin texture beneath. Lighting transformed from reflective to refractive, with light passing through the watery fabric, creating prismatic effects and caustic highlights on the skin. Editorial fashion photography, close-up composition, sharp focus, shallow depth of field, high-end studio lighting with refractive elements.",
    "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png",
    "size": "2K",
    "watermark": false
}'

Python Request Example

import requests
import os

# API configuration
api_key = os.environ.get("ARK_API_KEY", "your-api-key-here")  # Note: environment variable name is ARK_API_KEY
endpoint_path = "your-endpoint-path"  # Please replace with actual path
url = f"https://genaiapi.cloudsway.net/v1/ai/{endpoint_path}/seedream/image/generations"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}"
}

payload = {
    "prompt": "Keep the model's 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 flowing water, the model's skin details are visible. Lighting changes from reflective to refractive.",
    "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png",
    "size": "2K",
    "watermark": False
}

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    result = response.json()
    print("Generation successful!")
    print(result)
except requests.exceptions.RequestException as e:
    print(f"Request error: {e}")
    if hasattr(e, 'response') and e.response is not None:
        print(f"Response content: {e.response.text}")

Multi-image generation

Example of Curl Request

curl -X https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/seedream/image/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -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
}'

Python Request Example

import requests
import os

# Get API Key (assuming environment variable is set)
ARK_API_KEY = os.environ.get("ARK_API_KEY")
endpoint_path = "your-endpoint-path"  # Please replace with actual path

url = f"https://genaiapi.cloudsway.net/v1/ai/{endpoint_path}/seedream/image/generations"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {ARK_API_KEY}"
}

payload = {
    "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
}

response = requests.post(url, headers=headers, json=payload)

# Check response status
if response.status_code == 200:
    print("Request successful!")
    print(response.json())
else:
    print(f"Request failed, status code: {response.status_code}")
    print(response.text)

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]

Explanation of Streaming Response Events

Event Type	Description
image_generation.partial_succeeded	In streaming response mode, this event is returned when any image generation is successful
image_generation.partial_failed	In streaming return mode, this event is returned when any image generation fails. If the reason for failure is that the review fails: the system will still continue to request the next image generation task, i.e., it will not affect the generation process of other images within the same request. If the failure reason is an internal service exception (500), the next image generation task will not be requested.
image_generation.completed	Returned after all requested images (whether successful or failed) have been processed, this is the last response event of the streaming return

Example response when an error occurs

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

Attachment

Appendix 1: Recommended Width and Height Pixel Values for seedream 4.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: Preset Width and Height Values for seededit-3.0-i2i

Width/Height	Width	High
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	1144	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	1560	576
2.82	1536	544
3	1536	512

Appendix 3: Width and Height Pixel Values Recommended by seedream5

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
	2:3	2496x3744
	3:2	3744x2496
	21:9	4704x2016

MaaS_Seedream API

Request Protocol

Header

Request URL

Request Method

Request Parameters

Request Body Example

Text-to-Image

Example of Curl Request

Python Request Example

Response Example

Image-to-Image

Example of Curl Request

Python Request Example

Multi-image generation

Example of Curl Request

Python Request Example

Non-streaming Response Example

Streaming Response Example

Explanation of Streaming Response Events

Example response when an error occurs

Attachment

Appendix 1: Recommended Width and Height Pixel Values for seedream 4.5

Appendix 2: Preset Width and Height Values for seededit-3.0-i2i

Appendix 3: Width and Height Pixel Values Recommended by seedream5