Seedream
用 Seedream 生成和编辑图片:参数、返回与注意事项。
| 项目 | 值 |
|---|---|
| Base URL | https://api.hop-base.com/v1 |
| 生成(含参考图编辑) | POST /v1/images/generations |
| 编辑(multipart 兼容入口) | POST /v1/images/edits |
| 密钥分组 | 「Seedream 生图分组」 |
Seedream 同步返回结果(Lite 与 4.5 也可流式返回)。n 固定为 1,除组图与图层拆分外每次出 1 张;图片链接 24 小时有效。
可用型号
| 型号 | 模型 ID | 尺寸简写 | 官方价 |
|---|---|---|---|
| Seedream 5.5 | seedream-5-5 | 1K / 1.5K / 2K | $0.02起/ 张 |
| Seedream 5.0 Pro | seedream-5-0-pro | 1K / 1.5K / 2K | $0.0225起/ 张 |
| Seedream 5.0 Lite | seedream-5-0-lite | 2K / 3K / 4K | $0.035/ 张 |
| Seedream 4.5 | seedream-4-5 | 2K / 4K | $0.04/ 张 |
选型建议:要 1K 小图只能用 5.5 或 5.0 Pro,两者都是 1.5K 与 1K 同价、效果更好,建议优先 1.5K;Lite 与 4.5 最小输出 2K。
请求参数
生成
POST /v1/images/generations,JSON 请求体。加上 image 即为单图编辑、多图融合或局部编辑。
| 参数 | 必填 | 类型与限制 | 默认 | 说明 |
|---|---|---|---|---|
model | 必填 | 字符串,见上表 | — | 以当前密钥 GET /v1/models 的返回为准 |
prompt | 必填 | 字符串,去除首尾空白后非空 | — | 内容、构图、风格或编辑指令;开启 layer_decomposition 时可省略 |
size | 可选 | 型号尺寸简写,或 宽x高 | — | 仅 layer_decomposition 时可用 auto,像素范围见下表 |
n | 可选 | 只能为 1 | 1 | 其他值(含 null)返回 400;要多张请用 sequential_image_generation |
response_format | 可选 | 只能为 url / b64_json | url | url 返回签名直链;b64_json 在 data[].b64_json 返回 base64 |
output_format | 可选 | 按型号,见下表 | — | 输出图片格式 |
optimize_prompt_options | 可选 | 对象,mode 按型号取值 | — | 提示词优化模式 |
image | 可选 | URL / Data URL,字符串或字符串数组 | — | 参考图,传入即图生图 / 编辑 |
layer_decomposition | 可选 | 布尔,仅 seedream-5-0-pro | false | true 把 1 张输入图拆成底图 + 图层,见图层拆分 |
background | 可选 | opaque / transparent,仅 seedream-5-5 / seedream-5-0-pro | opaque | transparent 须恰好 1 张带透明通道的输入图,见透明背景 |
watermark | 可选 | 布尔 | false | true 加水印(官方默认 true) |
sequential_image_generation | 可选 | auto / disabled,仅 seedream-5-0-lite / seedream-4-5 | disabled | auto 返回一组图,见组图 |
sequential_image_generation_options | 可选 | 对象;max_images 为 1 至 15 的整数 | — | 组图张数上限;参考图数 + max_images ≤ 15 |
stream | 可选 | 布尔,仅 seedream-5-0-lite / seedream-4-5 | false | true 返回 SSE,见流式 |
按型号的限制:
| 模型 ID | size 总像素 | 参考图上限 | output_format | optimize_prompt_options.mode |
|---|---|---|---|---|
seedream-5-5 | 921,600–4,624,220 | 10 | png / jpeg | standard |
seedream-5-0-pro | 921,600–4,624,220 | 10 | png / jpeg | standard / fast |
seedream-5-0-lite | 3,686,400–16,777,216 | 14 | png / jpeg | standard |
seedream-4-5 | 3,686,400–16,777,216 | 14 | jpeg | standard |
宽x高 的宽高比须在 1:16–16:1 之间。size 不合规时在生成前返回 400,不计费。
image 的每一项是 http(s) URL 或 base64 编码的 Data URL,Data URL 单张 ≤ 30 MB。支持 JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF;URL 在提交时不下载、不检查大小,须是服务端能取得的公开地址。
局部编辑不用遮罩:把标注直接画在参考图上,并在 prompt 中描述坐标、bbox、箭头或涂画区域。
编辑
POST /v1/images/edits 是给已有 OpenAI Images 编辑代码用的兼容入口,推荐 multipart/form-data,也接受与生成相同的 JSON。至少要带 1 张参考图。
| 参数 | 必填 | 类型与限制 | 默认 | 说明 |
|---|---|---|---|---|
image / image[] | 必填 | 文件或 URL 字符串,可重复 | — | 上传文件单张 ≤ 30 MB |
model、prompt | 必填 | 同「生成」 | — | — |
size、n、response_format、output_format | 可选 | 同「生成」 | — | — |
background、watermark、stream、sequential_image_generation | 可选 | 同「生成」 | — | multipart 里布尔值写字符串 true / false |
sequential_image_generation_options[max_images] | 可选 | 同「生成」的 max_images | — | 也可写 max_images |
optimize_prompt_options[mode] | 可选 | 同「生成」的 mode | — | 也可写 optimize_prompt_mode |
layer_decomposition | 可选 | 同「生成」;multipart 传字符串 true | false | 须恰好 1 张 image |
请求里带 mask 字段即返回 400,传 null 也一样。multipart 中上表以外的字段会被忽略。
返回结果
同步返回标准 OpenAI Images JSON,图片在 data[].url;传 response_format: b64_json 时在 data[].b64_json。stream: true 时改为 SSE,见流式。
| 字段 | 类型 | 说明 |
|---|---|---|
created | integer | Unix 秒 |
model | string | 请求的模型 ID |
data[].url | string | 图片签名直链,24 小时有效 |
data[].b64_json | string | base64 图片数据,仅 response_format: b64_json 时返回 |
data[].error | object | 仅组图:这一张生成失败(code、message),不计费 |
data[].size | string | 实际输出的 宽x高 |
usage | object | 可能返回,含 generated_images 等用量 |
usage.cost | number | 本次扣费的人民币金额(与 usage.cost_usd 为同一笔扣费),最多 6 位小数。计费的同步成功响应都带 |
usage.cost_usd | number | 本次实际从余额扣除的美元金额,最多 8 位小数,与使用记录里这一条相同 |
usage.currency | string | usage.cost 的币种,恒为 CNY |
{
"model": "seedream-5-0-pro",
"created": 1760000000,
"data": [
{
"url": "https://…/result.jpeg?X-Signature=…",
"size": "2048x2048"
}
],
"usage": {
"generated_images": 1,
"output_tokens": 16384,
"total_tokens": 16384,
"cost": 1.53,
"cost_usd": 0.225,
"currency": "CNY"
}
}同步成功响应还带本次实际扣费:响应体的 usage.cost、usage.cost_usd 与 usage.currency,以及值相同的响应头 X-HopBase-Cost、X-HopBase-Cost-USD 与 X-HopBase-Currency。生成耗时较长(约 40 秒以上)、服务端已先发出 200 响应头保持连接时,响应头里没有扣费,请以响应体的 usage.cost_usd(美元,与使用记录一致)或 usage.cost(人民币)对账。未扣费的失败不带这些字段,流式响应也不带(请看使用记录)。详见扣费说明。
返回的 URL 是 24 小时有效的签名直链,过期后无法重新取得、只能重新生成(会再次计费),请收到后立即下载。
示例
文生图
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-pro",
"prompt": "霓虹夜色下的未来城市街景,电影感构图",
"size": "2048x2048",
"response_format": "url"
}'参考图编辑
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-你的密钥" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-pro",
"prompt": "把第一张图中的杯子移到桌面右侧,保持其余内容不变",
"image": ["https://example.com/source.png"],
"size": "2K",
"output_format": "png",
"response_format": "url"
}'组图
seedream-5-0-lite 与 seedream-4-5 可以一次返回一组相关的图(n 仍为 1)。传 "sequential_image_generation": "auto":模型按 prompt 决定出几张,不超过 sequential_image_generation_options.max_images(1 至 15 的整数;参考图数 + max_images 不超过 15)。请在 prompt 里描述整组内容,例如「同一角色四季的四张插画」。/v1/images/edits 的 multipart 写 sequential_image_generation_options[max_images](或 max_images)。
- 只按成功的张数计费。失败的那张(多为内容审核)以
data[].error(含code、message)返回、不计费;全部失败时请求返回 400 并带原因。 - 非流式组图要等整组生成完才返回,服务端最多等约 280 秒;张数多时请加
stream: true逐张接收。非流式组图不能用response_format: b64_json。
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
--max-time 300 \
-d '{
"model": "seedream-5-0-lite",
"prompt": "同一只柴犬春夏秋冬的四张插画",
"sequential_image_generation": "auto",
"sequential_image_generation_options": { "max_images": 4 },
"size": "2K"
}'流式
seedream-5-0-lite 与 seedream-4-5 接受 "stream": true,单图与组图都可用,响应为 SSE(text/event-stream)。seedream-5-5 与 seedream-5-0-pro 返回 400。
| 事件 | data |
|---|---|
image_generation.partial_succeeded | 一张图完成:image_index、url(或 b64_json)、size |
image_generation.partial_failed | 一张图失败:image_index、error.code、error.message;不计费 |
image_generation.completed | 全部结束:usage.generated_images、usage.output_tokens、usage.total_tokens |
每个事件的 data 都带 type、model、created,流以 data: [DONE] 结束。按成功张数计费。流式响应不带 usage.cost 与 X-HopBase-Cost 等响应头,扣费请看控制台使用记录。
curl -N https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-lite",
"prompt": "同一只柴犬春夏秋冬的四张插画",
"sequential_image_generation": "auto",
"sequential_image_generation_options": { "max_images": 4 },
"stream": true
}'event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","model":"seedream-5-0-lite","created":1792723998,"image_index":0,"url":"https://…","size":"2048x2048"}
event: image_generation.completed
data: {"type":"image_generation.completed","model":"seedream-5-0-lite","created":1792723998,"usage":{"generated_images":1,"output_tokens":16384,"total_tokens":16384}}
data: [DONE]透明背景
seedream-5-5 与 seedream-5-0-pro 接受 background:opaque / transparent,默认 opaque。transparent 只用于图生图:须恰好 1 张带透明通道的输入图,例如 PNG(JPEG、BMP 的 Data URL 返回 400)。输出为带透明通道的 PNG,所以 output_format: jpeg 返回 400。其他型号传 background 返回 400。
curl https://api.hop-base.com/v1/images/edits \
-H "Authorization: Bearer sk-your-key" \
-F "model=seedream-5-0-pro" \
-F "prompt=保留商品主体,背景改为透明" \
-F "image=@product.png" \
-F "background=transparent" \
-F "output_format=png"图层拆分
seedream-5-0-pro 可以把 1 张图拆成底图 + 至多 16 个透明图层(主体、文字、背景、装饰),方便逐层修改或挪动后再合成。在 POST /v1/images/generations 传 JSON 布尔 "layer_decomposition": true,或在 POST /v1/images/edits 传字段 layer_decomposition=true(multipart 或 JSON 均可)。
开启后以下规则改变:
| 参数 | layer_decomposition: true 时 |
|---|---|
model | 仅 seedream-5-0-pro,其他型号返回 400 |
image | 恰好 1 张;Data URL 须为 PNG 或 JPEG |
prompt | 可选。不传时模型自动识别主体、文字、背景与装饰;也可描述要拆出的内容,或用 <bbox>x1 y1 x2 y2</bbox>(0–999 归一化坐标)指定区域 |
size | 只认 1K / 1.5K / 2K / auto,缺省 auto;不接受 宽x高 |
output_format | 只作用于底图;图层恒为带透明通道的 PNG |
auto 时,输入图介于约 1280x720 与 2048x2048 之间则保持原尺寸,更小输出 1K、更大输出 2K。输入图官方限制:总像素 512x512 至 6000x6000,宽高比 1:16 至 16:1,不超过 30 MB。
图层拆分是同步调用且较慢:1K 约需 1.5 分钟。请把客户端超时设为至少 5 分钟;首个请求还在进行时不要重发,它仍可能完成并计费。
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
--max-time 300 \
-d '{
"model": "seedream-5-0-pro",
"image": "https://example.com/poster.png",
"layer_decomposition": true,
"size": "1K"
}'data[] 先是底图,后面是各图层:
{
"model": "seedream-5-0-pro",
"created": 1792722728,
"data": [
{
"url": "https://…/base.jpeg?X-Signature=…",
"size": "880x1088",
"output_format": "jpeg",
"z_index": 0
},
{
"url": "https://…/layer-1.png?X-Signature=…",
"size": "959x354",
"output_format": "png",
"z_index": 1,
"bounding_box": {
"absolute": [156, 751, 784, 983],
"normalized": [177, 690, 890, 903]
},
"name": "Wooden stump stage",
"description": "A wooden stump stage at the bottom of the scene"
}
],
"usage": {
"generated_images": 2
}
}| 字段 | 说明 |
|---|---|
data[].z_index | 0 是底图;图层从 1 起递增,数字越大越靠上 |
data[].url | 签名直链,24 小时有效 |
data[].size | 这张图的实际像素尺寸;图层图片尺寸通常与它在底图上的框不同 |
data[].output_format | 底图按请求的 output_format;图层为 png |
data[].bounding_box.absolute | 仅图层:在底图上的 [left, top, right, bottom] 像素坐标 |
data[].bounding_box.normalized | 仅图层:同一框的 0–999 归一化坐标 |
data[].name、data[].description | 仅图层:图层名与内容描述 |
usage.generated_images | 底图 + 图层的张数,即计费张数 |
合成时以底图为画布,按 z_index 升序叠放:把每个图层缩放到框的尺寸 (right - left) x (bottom - top),按透明通道贴到 (left, top)。以 Pillow 为例:
import io
import urllib.request
from PIL import Image
def fetch(url):
return Image.open(io.BytesIO(urllib.request.urlopen(url).read())).convert("RGBA")
items = sorted(resp["data"], key=lambda d: d["z_index"]) # resp 为解析后的响应 JSON
canvas = fetch(items[0]["url"])
for item in items[1:]:
left, top, right, bottom = item["bounding_box"]["absolute"]
layer = fetch(item["url"]).resize((right - left, bottom - top))
canvas.alpha_composite(layer, (left, top))
canvas.save("recomposed.png")注意事项
n只能为 1:每次出 1 张,组图(sequential_image_generation: auto,Lite 与 4.5)与图层拆分(5.0 Pro)除外。- 只支持同步:
Prefer: respond-async会被忽略,照常同步返回。 - 默认返回
url;要 base64 请传response_format: b64_json(非流式组图须同时stream: true)。 size不接受auto(图层拆分除外),Lite 与 4.5 的最小输出是 2K。seedream-4-5只输出 JPEG。seedream-5-5的optimize_prompt_options.mode只接受standard(传fast返回 400),不支持图层拆分、组图与流式。- 不支持传统 mask,局部编辑请用带标注的参考图加 prompt 描述。
- 复数
images、quality等字段不生效,会被忽略。 - 暂不支持
tools(联网搜索),传入返回 400。 seedream-5-0-lite是 Seedream 5.0 的轻量版,公开模型名为 Seedream 5.0 Lite,请勿当作 Pro 使用。- Data URL 必须是 base64 编码,MIME 须与图片一致。
- 官方规格:输入单张最多 30 MB / 36MP。
常见报错
参数不合规在生成前返回 400,不计费。内容安全拦截也返回 400、不计费,原因在 error.message 中。
| 报错 | 改法 |
|---|---|
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size | 改用该型号的尺寸简写或合法 宽x高 |
model seedream-5-5 only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size | 改用 1K、1.5K、2K 或合法 宽x高;不接受 4K |
model seedream-5-0-lite requires the total pixel count of size to be between 3686400 and 16777216 | 把宽高调到总像素区间内 |
size aspect ratio must be between 1:16 and 16:1 | 调整宽高比 |
only a single output is supported (n=1) | 去掉 n;要多张请用 sequential_image_generation |
response_format only supports url or b64_json | 改为 url 或 b64_json |
model seedream-4-5 only supports output_format jpeg | 改传 jpeg 或不传 |
model seedream-5-5 only supports optimize_prompt_options.mode standard | 改传 standard 或不传;fast 请用 seedream-5-0-pro |
at most 10 reference images are supported | 减少参考图张数 |
seedream does not accept a traditional mask; ... | 去掉 mask,改用带标注的参考图 |
model seedream-5-0-lite does not support layer_decomposition | 图层拆分请用 seedream-5-0-pro |
layer_decomposition requires exactly one image | 只传 1 张 image |
layer_decomposition only accepts png or jpeg images | 把输入图转成 PNG 或 JPEG |
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decomposition | 改用档位,或不传 size |
layer_decomposition must be a boolean | 传 true 或 false |
model seedream-5-0-lite does not support background | background 请用 seedream-5-5 或 seedream-5-0-pro |
background transparent requires exactly one image with an alpha channel | 只传 1 张带透明通道的图,例如 PNG |
background transparent outputs png; output_format jpeg is not allowed | 去掉 output_format 或改为 png |
model seedream-5-0-pro does not support sequential_image_generation | 组图请用 seedream-5-0-lite 或 seedream-4-5 |
the number of reference images plus max_images must not exceed 15 | 调小 max_images 或少传参考图 |
response_format b64_json with sequential_image_generation auto requires stream=true | 加 stream: true,或改用 url |
model seedream-5-0-pro does not support stream | 流式请用 seedream-5-0-lite 或 seedream-4-5 |
model seedream-5-0-lite does not support tools | 去掉 tools |
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size # 例如 "size": "auto"
model seedream-5-5 only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size # 例如 "size": "4K"
model seedream-5-0-lite requires the total pixel count of size to be between 3686400 and 16777216
size aspect ratio must be between 1:16 and 16:1
missing prompt
response_format only supports url or b64_json
only a single output is supported (n=1)
model seedream-4-5 only supports output_format jpeg
model seedream-5-0-lite only supports optimize_prompt_options.mode standard
model seedream-5-5 only supports optimize_prompt_options.mode standard # fast 仅 seedream-5-0-pro
optimize_prompt_options must be an object
image must be a URL/data URL string or an array of strings
every item in the image array must be a URL or data URL string
image must not be empty
at most 10 reference images are supported
reference image 1 is invalid: data URL must be base64-encoded
reference image 1 is invalid: unsupported image format image/svg+xml
reference image 1 is invalid: a single image must not exceed 30 MB
image edits require at least one image reference # /v1/images/edits 未带图
seedream does not accept a traditional mask; ... # /v1/images/edits 带 "mask" 即拒,null 也一样
model seedream-5-0-lite does not support layer_decomposition # 只有 seedream-5-0-pro 支持
layer_decomposition must be a boolean
layer_decomposition requires exactly one image # 没传图,或传了 2 张以上
layer_decomposition only accepts png or jpeg images # Data URL 是其他格式
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decomposition
model seedream-5-0-lite does not support background # 仅 seedream-5-5 / seedream-5-0-pro 支持
model seedream-5-0-pro only supports background opaque or transparent
background transparent requires exactly one image with an alpha channel
background transparent outputs png; output_format jpeg is not allowed
background transparent requires an input image with an alpha channel, image/jpeg is not supported
model seedream-5-0-pro does not support sequential_image_generation # 组图与流式:仅 seedream-5-0-lite / seedream-4-5
sequential_image_generation only supports auto or disabled
sequential_image_generation_options must be an object
sequential_image_generation_options.max_images must be an integer between 1 and 15
the number of reference images plus max_images must not exceed 15
response_format b64_json with sequential_image_generation auto requires stream=true
model seedream-5-0-pro does not support stream
watermark must be a boolean
model seedream-5-0-lite does not support tools # 暂不支持联网搜索计费
按成功生成的张数计费(组图里失败的那几张不计费),5.5 与 5.0 Pro 每张参考图另外计费;生成失败与安全拦截不计费。5.5 与 5.0 Pro 按输出像素分档计价,1K 与 1.5K 同价。每次请求的实际扣费见响应里的 usage.cost_usd(美元)与 usage.cost(人民币)。图层拆分时,每张输出图(底图和每个图层)各按自身像素档以图层拆分单价计费,为 5.0 Pro 普通单张价的一半;输入图照常按参考图计费。usage.generated_images 即计费的输出张数。流式响应不带扣费字段,请看使用记录。
单价见各型号的模型卡与登录后的模型广场。