Skip to main content
POST

Authorizations

string
必填
所有接口均需要使用Bearer Token进行认证获取 API Key:访问 API Key 管理页面 获取您的 API Key使用时在请求头中添加:
单图模型seedream-5-0-pro 每次请求仅生成 1 张图像(图层拆分除外)。以下参数会直接拒绝(返回 400,不建任务、不扣费):
  • n > 1
  • sequential_image_generation(不支持组图)
  • stream(不支持流式输出)
  • tools(不支持联网搜索)
  • image_urls 超过 10 张

交互编辑

在提示词中使用 <point> / <bbox> 坐标,或上传带手绘标记的图片,精确指定编辑位置。
  • 点选坐标:<point>x y</point>(指定一个点,由模型判断影响范围)
  • 框选坐标:<bbox>x1 y1 x2 y2</bbox>(指定左上角和右下角坐标,精确控制编辑区域大小)

图层拆分

将一张图片拆成 1 张底图和最多 16 个透明 PNG 图层,并返回位置与层级信息。

Body

string
默认值:"seedream-5-0-pro"
必填
图像生成模型名称
  • seedream-5-0-pro(推荐)
  • 亦接受:seedream-5.0-pro
boolean
默认值:"false"
是否在提交图片任务前执行内容审核。
  • true:使用 omni-moderation-latest 审核提示词和输入图片
  • false 或不传:不发起审核请求,不增加审核成本与延迟(默认)
string
必填
图像生成的文本描述使用 layer_decomposition: true 时可省略;省略后模型会自动识别并拆分图片中的主要元素。除中英文外,还支持俄语、阿拉伯语、菲律宾语、泰语、土耳其语、韩语、马来语、西班牙语、葡萄牙语、印度尼西亚语、法语、德语、越南语和日语的原生文字生成。
建议: 控制在 600 英文单词以内,描述过长可能导致细节丢失。
string
默认值:"1K"
分辨率档位(兼容小写)。这是本站提供的扩展字段,等价于将档位直接写在 size 中。
  • 1K(默认)
  • 1.5K(与 1K 同价,画质更好,无特殊理由建议优先用 1.5K)
  • 2K
传入 3K / 4K 等不支持档位会返回 400。同时传入档位形式的 sizeresolution 时,以 size 为准。
size精确像素值(如 2048x1024)时,本字段被忽略,尺寸完全由 size 决定。
string
默认值:"auto"
档位关键字、宽高比、auto,或精确像素值

写法 ①:指定档位(推荐)

档位可以直接写在 size 中,也可以使用本站扩展字段 resolution
上面两种写法等价。只指定档位时,可在 prompt 中描述“竖版海报”“横版封面”等用途,由模型决定宽高比。

写法 ②:档位 + 宽高比

resolution 配合使用。支持的宽高比:
  • 1:14:33:416:99:163:22:32:11:221:9
  • 兼容 16x9 这种 x 写法;2x12:1 等价,1x21:2 等价
  • 别名中的 x 必须小写,且不能包含空格
  • auto(默认):只下发分辨率档位,最终宽高比由模型根据 prompt / 参考图自动判断
列表外的宽高比(如 9:21)直接返回 400,不会静默回退成 1:1档位 × 比例 → 实际输出像素:

写法 ③:精确像素

size 写成 宽x高按像素输出resolution 不参与。兼容 2048X1024 / 2048×1024
限制的是宽高乘积,不是单边。例如 512×512 总像素过低会 400;2048×1024 合法。
string
默认值:"opaque"
输出背景模式:
  • opaque:实体背景(默认)
  • transparent:透明背景
transparent 只能用于图生图,并且必须恰好传入 1 张本身带透明通道的输入图;同时必须设置 output_format: "png"
boolean
默认值:"false"
是否进行图层拆分。开启后,模型会输出 1 张底图和最多 16 个带透明通道的 PNG 图层。开启时必须恰好传入 1 张 PNG 或 JPEG 图片,图片总像素须在 [262144, 36000000] 内且大小不超过 30 MB;size 只接受 1K1.5K2Kauto,默认 autooutput_format 只控制底图格式,拆出的图层恒为 PNG。
object
默认值:"{\"mode\":\"standard\"}"
提示词优化模式:
  • standard:标准模式,质量更好(默认)
兼容扁平写法:"optimize_prompt_options.mode": "standard"
integer
默认值:"1"
生成图片数量。只能是 1;需要组图生成时请改用 seedream-5-0-lite
array
参考图像的 URL 列表,用于单图 / 多参考图生图,最多 10 张支持两种格式:1. 公网 URL
  • http://https:// 可访问链接
  • 示例:https://example.com/image.jpg
2. Base64(Data URI)
  • 格式:data:image/<格式>;base64,<编码><格式> 必须小写
  • 示例:data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABg...
单张图片限制:
  • 格式:jpeg / png / webp / bmp / tiff / gif / heic / heif
  • 宽高比(宽/高):[1/16, 16]
  • 单边 > 14 px
  • 大小 ≤ 30 MB
  • 总像素 ≤ 6000×6000(36,000,000)
计费: 第 1 张参考图免费,第 2 张起每张加收固定单价。
string
默认值:"jpeg"
输出图片格式
  • jpeg(默认)
  • png
兼容: response_formatoutput_format 等价,其余取值按 jpeg 处理。
boolean
默认值:"false"
是否在生成图像右下角添加 “AI generated” 水印
  • true:添加
  • false:不添加(默认)

请求示例

文生图(档位 + 比例)

文生图(精确像素)

多参考图

推荐:1.5K 同价更好画质

图层拆分

也可以使用归一化到 0–1000<bbox> 坐标精确指定要拆出的元素:

交互编辑

用自然语言描述图片中的手绘标记:
或使用 <point> / <bbox> 精准定位:

透明通道编辑

完整示例:提交并获取图片

下面的脚本完整展示了提交异步任务、轮询任务状态、处理失败状态并读取最终图片地址的流程。复制前请替换 YOUR_API_KEY
Python
成功时,任务查询接口返回:
返回图片已镜像到平台自有存储。仍建议在业务侧及时下载并持久化,不要把结果 URL 当作永久存储。

完整 cURL 场景示例

多图融合(最多 10 张参考图)

精确像素、提示词优化与水印

拆分并单独编辑透明图层

第一步,拆分原图:
第二步,取得某个透明图层的 URL 后单独编辑:

图层拆分响应与重组

urlsizesoutput_formatslayers 数组按下标一一对应,下标 0 恒为底图:
z_index 从小到大叠放。使用绝对坐标还原到输出底图时:
还原到任意 W × H 画布时,使用归一化坐标:
图层拆分按张收费。提交时按最多 17 张预扣;任务完成后,按每张图片的实际输出像素逐张判档并结算,多扣的自动退回。账户余额必须足以覆盖 17 张预扣;size: "auto" 按 2K 档预扣。

计费说明

输出图按每张图片的实际总像素分档(约 2.61M = 2,601,124):
  • 1.5K 与 1K 同价(均为 $0.045)。
  • size 为精确像素时按实际输出面积计费,resolution 不影响(例如 size: "2048x2048" 按 $0.09)。
  • 第 1 张参考图免费,第 2 张起每张另计参考图加价。
  • 任务失败自动全额退款。

图层拆分的预扣与结算

提交任务时尚不知道最终会生成多少图层及其尺寸,因此按请求参数保守预扣:
  • 精确像素:按该像素面积判档。
  • 1K / 1.5K:按 1K 档预扣。
  • 2K:按 2K 档预扣。
  • auto:最高可输出到 2K,因此按 2K 档预扣。
任务完成后,以底图和每个实际图层的真实像素面积逐张判档并求和,多扣的额度自动退回。图层通常远小于底图,因此即使按 2K 档预扣,最终也可能全部按 1K 档结算。
例如:一张 1080×1080 输入图最终拆成 10 张图片。提交时按 17 张 × 2K 档 预扣;如果最终 10 张图片都不超过 261 万像素,则按 10 张 × 1K 档 结算,剩余额度自动退回。

常见错误

⏱️ 生成较慢:1K 约 90 秒、2K 约 160 秒(质量优先)。提交后每 5~10 秒轮询一次 获取任务状态,客户端超时建议 5 分钟。请及时保存生成结果。

Response

integer
响应状态码
array
返回数据数组