跳到正文

Seedream

用 Seedream 生成和编辑图片:参数、返回与注意事项。

项目值
Base URLhttps://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.5seedream-5-51K / 1.5K / 2K$0.02起/ 张
Seedream 5.0 Proseedream-5-0-pro1K / 1.5K / 2K$0.0225起/ 张
Seedream 5.0 Liteseedream-5-0-lite2K / 3K / 4K$0.035/ 张
Seedream 4.5seedream-4-52K / 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可选只能为 11其他值(含 null)返回 400;要多张请用 sequential_image_generation
response_format可选只能为 url / b64_jsonurlurl 返回签名直链;b64_json 在 data[].b64_json 返回 base64
output_format可选按型号,见下表—输出图片格式
optimize_prompt_options可选对象,mode 按型号取值—提示词优化模式
image可选URL / Data URL,字符串或字符串数组—参考图,传入即图生图 / 编辑
layer_decomposition可选布尔,仅 seedream-5-0-profalsetrue 把 1 张输入图拆成底图 + 图层,见图层拆分
background可选opaque / transparent,仅 seedream-5-5 / seedream-5-0-proopaquetransparent 须恰好 1 张带透明通道的输入图,见透明背景
watermark可选布尔falsetrue 加水印(官方默认 true)
sequential_image_generation可选auto / disabled,仅 seedream-5-0-lite / seedream-4-5disabledauto 返回一组图,见组图
sequential_image_generation_options可选对象;max_images 为 1 至 15 的整数—组图张数上限;参考图数 + max_images ≤ 15
stream可选布尔,仅 seedream-5-0-lite / seedream-4-5falsetrue 返回 SSE,见流式

按型号的限制:

模型 IDsize 总像素参考图上限output_formatoptimize_prompt_options.mode
seedream-5-5921,600–4,624,22010png / jpegstandard
seedream-5-0-pro921,600–4,624,22010png / jpegstandard / fast
seedream-5-0-lite3,686,400–16,777,21614png / jpegstandard
seedream-4-53,686,400–16,777,21614jpegstandard

宽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 传字符串 truefalse须恰好 1 张 image

请求里带 mask 字段即返回 400,传 null 也一样。multipart 中上表以外的字段会被忽略。

返回结果

同步返回标准 OpenAI Images JSON,图片在 data[].url;传 response_format: b64_json 时在 data[].b64_json。stream: true 时改为 SSE,见流式。

字段类型说明
createdintegerUnix 秒
modelstring请求的模型 ID
data[].urlstring图片签名直链,24 小时有效
data[].b64_jsonstringbase64 图片数据,仅 response_format: b64_json 时返回
data[].errorobject仅组图:这一张生成失败(code、message),不计费
data[].sizestring实际输出的 宽x高
usageobject可能返回,含 generated_images 等用量
usage.costnumber本次扣费的人民币金额(与 usage.cost_usd 为同一笔扣费),最多 6 位小数。计费的同步成功响应都带
usage.cost_usdnumber本次实际从余额扣除的美元金额,最多 8 位小数,与使用记录里这一条相同
usage.currencystringusage.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_index0 是底图;图层从 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 描述。

常见报错

参数不合规在生成前返回 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 backgroundbackground 请用 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

计费

按成功生成的张数计费(组图里失败的那几张不计费),5.5 与 5.0 Pro 每张参考图另外计费;生成失败与安全拦截不计费。5.5 与 5.0 Pro 按输出像素分档计价,1K 与 1.5K 同价。每次请求的实际扣费见响应里的 usage.cost_usd(美元)与 usage.cost(人民币)。图层拆分时,每张输出图(底图和每个图层)各按自身像素档以图层拆分单价计费,为 5.0 Pro 普通单张价的一半;输入图照常按参考图计费。usage.generated_images 即计费的输出张数。流式响应不带扣费字段,请看使用记录。

单价见各型号的模型卡与登录后的模型广场。

下一步