MaaS_Seedream系列接口文档

请求协议

http

请求URL

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

请求方法

POST

请求参数

参数名	类型	是否必需	描述
prompt	string	是	用于生成图像的提示词，支持中英文，建议不超过300个汉字或600个英文单词。字数过多信息容易分散，模型可能因此忽略细节，只关注重点，造成图片缺失部分元素。
image	string/array	否	输入的图片信息，支持 URL 或 Base64 编码。其中，MaaS_Seedream_5.0_lite/4.5/4.0 支持单图或多图输入，seededit-3.0-i2i 仅支持单图输入图片URL：请确保图片URL可被访问。 Base64编码：请遵循此格式data:image/<图片格式>;base64,<Base64编码>。注意 <图片格式> 需小写，如 data:image/png;base64,<base64_image> 说明：传入图片需要满足以下条件：图片格式：jpeg、png（MaaS_Seedream_5.0_lite/4.5/4.0 模型新增支持 webp、bmp、tiff、gif 格式）宽高比（宽/高）范围： [1/16, 16] (适用模型：MaaS_Seedream_5.0_lite/4.5/4.0） [1/3, 3] (适用模型：seedream-3.0-t2i、seededit-3.0-i2i）宽高长度（px） > 14 大小：不超过 10MB 总像素：不超过 6000x6000=36000000 px （对单张图宽度和高度的像素乘积限制，而不是对宽度或高度的单独值进行限制） MaaS_Seedream_5.0_lite/4.5/4.0 最多支持传入 14 张参考图。
size	string	否	指定生成图像的尺寸信息，支持以下两种方式，不可混用。方式 1 \| 指定生成图像的分辨率，并在prompt中用自然语言描述图片宽高比、图片形状或图片用途，最终由模型判断生成图片的大小。可选值：MaaS_Seedream_5.0_lite（2K、3K）、doubao-seedream-4.5（2K、4K）、doubao-seedream-4.0（1K、2K、4K）方式 2 \| 指定生成图像的宽高像素值，常见推荐值见附表：默认值：2048x2048 总像素取值范围：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] ）宽高比取值范围：[1/16, 16] 说明：采用方式 2 时，需同时满足总像素取值范围和宽高比取值范围。其中，总像素是对宽度和高度的像素乘积限制，而不是对宽度或高度的单独值进行限制。
seed	integer	否	默认值-1，仅seededit-3.0-i2i支持该参数，随机数种子，用于控制模型生成内容的随机性。取值范围为 [-1, 2147483647]。
sequential_image_generation	string	否	仅 MaaS_Seedream_5.0_lite/4.5/4.0 支持该参数控制是否关闭组图功能，默认值disabled auto：自动判断模式，模型会根据用户提供的提示词自主判断是否返回组图以及组图包含的图片数量。 disabled：关闭组图功能，模型只会生成一张图。
sequential_image_generation_options	object	否	仅 MaaS_Seedream_5.0_lite/4.5/4.0 支持该参数,组图功能的配置。仅当 sequential_image_generation 为 auto 时生效.
sequential_image_generation_options.max_images	integer	否	指定本次请求，最多可生成的图片数量，默认值15。取值范围： [1, 15] 说明：实际可生成的图片数量，除受到 max_images 影响外，还受到输入的参考图数量影响。输入的参考图数量+最终生成的图片数量≤15张。
stream	boolean	否	仅 MaaS_Seedream_5.0_lite/4.5/4.0 支持该参数默认值false，控制是否开启流式输出模式。 false：非流式输出模式，等待所有图片全部生成结束后再一次性返回所有信息。 true：流式输出模式，即时返回每张图片输出的结果。在生成单图和组图的场景下，流式输出模式均生效。
tools	Array	否	仅MaaS_Seedream_5.0_lite支持该参数
type	string	否	仅MaaS_Seedream_5.0_lite支持该参数 web_search (目前唯一可选值)
guidance_scale	float	否	MaaS-seedream-3.0-t2i 默认值 2.5 MaaS-seededit-3.0-i2i 默认值 5.5 MaaS_Seedream_5.0_lite/4.5/4.0 不支持模型输出结果与prompt的一致程度，生成图像的自由度，又称为文本权重；值越大，模型自由度越小，与用户输入的提示词相关性越强。取值范围：[1, 10] 。
response_format	string	否	指定生成图像的返回格式，默认值url。生成的图片为 jpeg 格式，支持以下两种返回方式： url：返回图片下载链接；链接在图片生成后24小时内有效，请及时下载图片。 b64_json：以 Base64 编码字符串的 JSON 格式返回图像数据。
watermark	boolean	否	是否在生成的图片中添加水印，默认值true。 false：不添加水印。 true：在图片右下角添加“AI生成”字样的水印标识
output_format	string	否	仅>MaaS_Seedream_5.0_lite支持该参数 jpeg (默认值) png
optimize_prompt_options	object	否	提示词优化功能的配置 seededit-3.0-i2i不支持该参数
optimize_prompt_options.mode	string	否	设置提示词优化功能使用的模式，默认值standard。 standard：标准模式，生成内容的质量更高，耗时较长。 fast：快速模式，生成内容的耗时更短，质量一般。MaaS_Seedream_5.0_lite/4.5 不支持

请求体示例

文生图

Curl 请求示例

curl https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/seedream/image/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "prompt": "充满活力的特写编辑肖像，模特眼神犀利，头戴雕塑感帽子，色彩拼接丰富，眼部焦点锐利，景深较浅，具有Vogue杂志封面的美学风格，采用中画幅拍摄，工作室灯光效果强烈。",
    "size": "2K",
    "watermark": false
}'

Python 请求示例

import requests
import os

# API 配置
api_key = os.environ.get("API_KEY", "your-api-key-here")  # 建议从环境变量获取
endpoint_path = "your-endpoint-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": "充满活力的特写编辑肖像，模特眼神犀利，头戴雕塑感帽子，色彩拼接丰富，眼部焦点锐利，景深较浅，具有Vogue杂志封面的美学风格，采用中画幅拍摄，工作室灯光效果强烈。",
    "size": "2K",
    "watermark": False
}

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()  # 检查请求是否成功
    result = response.json()
    print("生成成功！")
    print(result)
except requests.exceptions.RequestException as e:
    print(f"请求出错: {e}")
    if hasattr(e, 'response') and e.response is not None:
        print(f"响应内容: {e.response.text}")

响应示例

{
  "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": "充满活力的特写编辑肖像，模特眼神犀利，头戴雕塑感帽子，色彩拼接丰富，眼部焦点锐利，景深较浅，具有Vogue杂志封面的美学风格，采用中画幅拍摄，工作室灯光效果强烈。",
      "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"
  }
}

图生图

Curl 请求示例

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": "保持模特姿势和液态服装的流动形状不变。将服装材质从银色金属改为完全透明的清水（或玻璃）。透过液态水流，可以看到模特的皮肤细节。光影从反射变为折射。",
    "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png",
    "size": "2K",
    "watermark": false
}'

Python 请求示例

import requests
import os

# API 配置
api_key = os.environ.get("ARK_API_KEY", "your-api-key-here")  # 注意环境变量名是 ARK_API_KEY
endpoint_path = "your-endpoint-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": "保持模特姿势和液态服装的流动形状不变。将服装材质从银色金属改为完全透明的清水（或玻璃）。透过液态水流，可以看到模特的皮肤细节。光影从反射变为折射。",
    "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("生成成功！")
    print(result)
except requests.exceptions.RequestException as e:
    print(f"请求出错: {e}")
    if hasattr(e, 'response') and e.response is not None:
        print(f"响应内容: {e.response.text}")

多图生图

Curl 请求示例

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": "将图1的服装换为图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 请求示例

import requests
import os

# 获取 API Key（假设环境变量已设置）
ARK_API_KEY = os.environ.get("ARK_API_KEY")

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

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

payload = {
    "prompt": "将图1的服装换为图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)

# 检查响应状态
if response.status_code == 200:
    print("请求成功！")
    print(response.json())
else:
    print(f"请求失败，状态码: {response.status_code}")
    print(response.text)

非流式响应示例

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

流式响应示例

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]

流式响应事件说明

事件类型	说明
image_generation.partial_succeeded	在流式响应模式下，当任意图片生成成功时返回该事件
image_generation.partial_failed	在流式返回模式下，当任意图片生成失败时返回该事件。若失败原因为审核不通过：仍会继续请求下一个图片生成任务，即不影响同请求内其他图片的生成流程。若失败原因为内部服务异常（500）：不会继续请求下一个图片生成任务。
image_generation.completed	请求的所有图片（无论成功或失败）均处理完毕后返回，是该流式返回的最后一个响应事件

发生错误时的响应示例

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

附件

附表1：seedream4.5推荐的宽高像素值

宽高比	宽高像素值
1:1	2048x2048
4:3	2304x1728
3:4	1728x2304
16:9	2560x1440
9:16	1440x2560
3:2	2496x1664
2:3	1664x2496
21:9	3024x1296

附表2：seededit-3.0-i2i 预设宽高值

宽/高	宽	高
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

附表3：seedream5推荐的宽高像素值

分辨率	宽高比	宽高像素值
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系列接口文档

请求协议

Header

请求URL

请求方法

请求参数

请求体示例

文生图

Curl 请求示例

Python 请求示例

响应示例

图生图

Curl 请求示例

Python 请求示例

多图生图

Curl 请求示例

Python 请求示例

非流式响应示例

流式响应示例

流式响应事件说明

发生错误时的响应示例

附件

附表1：seedream4.5推荐的宽高像素值

附表2：seededit-3.0-i2i 预设宽高值

附表3：seedream5推荐的宽高像素值