Seedream 图像生成（火山方舟原生协议）

模型与档位

• 四个模型走同一入口 POST /api/v3/images/generations，能力均为文生图、图生图（单图 / 多图参考），必填 model、prompt。
• doubao-seedream-5.0 是 doubao-seedream-5.0-lite 的别名：方舟没有独立的 5.0 模型，二者档位与单价完全一致。
• 5.0 pro 不提供 3K / 4K；5.0 lite / 5.0 / 4.5 不提供 1K / 1.5K（方舟要求总像素 ≥ 3,686,400）；4.5 另外不提供 3K。表外档位在创建时被拒（HTTP 400），不渲染、不计费。
• 5.0 pro 的 1.5K 与 1K 同价（方舟定价），且只有部分供应商能出该档位，可用线路少于其他档位。

ModelGo 按火山引擎方舟 Images API 的官方路径与请求/响应格式原样接收 Seedream 请求，网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。图像同步返回，无需轮询。

使用方舟官方 SDK（volcenginesdkarkruntime）时，把 base_url 指向 https://api.modelgo.com/api/v3、api_key 换成 ModelGo API Key 即可。

1. 创建图像

POST https://api.modelgo.com/api/v3/images/generations

文生图（5.0 pro）

curl https://api.modelgo.com/api/v3/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5.0-pro",
    "prompt": "一只毛茸茸的橘猫坐在阳光下的窗台上，16:9 横构图，胶片质感",
    "size": "2K",
    "watermark": false
  }'

文生图（5.0 lite）

curl https://api.modelgo.com/api/v3/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5.0-lite",
    "prompt": "一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感",
    "size": "2K",
    "watermark": false
  }'

图生图 / 多图参考

curl https://api.modelgo.com/api/v3/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5.0-pro",
    "prompt": "把第一张图的猫放到第二张图的霓虹街景里",
    "image": ["https://example-cdn.com/cat.jpg", "https://example-cdn.com/street.jpg"],
    "size": "1280x720",
    "response_format": "b64_json"
  }'

响应

{
  "model": "doubao-seedream-5.0-pro",
  "created": 1757318400,
  "data": [{"url": "https://ark-content-generation.tos-cn-beijing.volces.com/...", "size": "2816x1584", "output_format": "jpeg"}],
  "usage": {"generated_images": 1, "input_images": 0, "output_tokens": 17424, "total_tokens": 17424}
}

• model 始终回显你请求的逻辑模型名（如 doubao-seedream-5.0-lite），不是方舟内部的版本 id（形如 doubao-seedream-5-0-260128 / doubao-seedream-4-5-251128 / doubao-seedream-5-0-pro-260628）。
• response_format 缺省 url，链接 24 小时内有效，请及时下载，不要持久化该 URL。
• response_format: "b64_json" 时 data[].b64_json 直接给出 base64 图像。
• data[].size 是实际输出像素，output_format 是实际编码格式。
• usage.output_tokens / total_tokens 为上游回显的参考值，不参与计费；结算只看 usage.generated_images。

保存到文件：

curl -s https://api.modelgo.com/api/v3/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedream-5.0-lite","prompt":"a red ball on a wooden table","size":"2K","response_format":"b64_json"}' \
  | python3 -c 'import sys,json,base64; open("out.jpg","wb").write(base64.b64decode(json.load(sys.stdin)["data"][0]["b64_json"]))'

2. 参数说明

• sequential_image_generation: "auto"（组图）在 5.0 pro 上不支持 → 400。
• stream: true → 400：不支持流式。
• 请求体中出现上表之外的字段 → 400，不会被忽略。
• 按可交付档位选路。 网关只把请求交给能按所声明 size 交付的供应商；若当前无供应商能出该档位，返回 400，不产生费用。

分辨率档位

• 表外的 size（该模型不提供的档位、像素低于下限或宽高比越界）在创建时被拒（HTTP 400），不会静默降档或升档生成，也不产生费用。

参考图的要求

• 必须是上游服务器能直接 GET 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie。
• 部分站点直链对非浏览器抓取返回 403，会导致请求失败，不计费。建议使用自有对象存储或 CDN 地址。

3. 完整示例（Python，方舟官方 SDK）

import os, requests
from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ["MODELGO_API_KEY"], base_url="https://api.modelgo.com/api/v3")

# 5.0 pro：档位 + 提示词里的构图比例
r = client.images.generate(model="doubao-seedream-5.0-pro",
                           prompt="一只橘猫坐在窗台上，16:9 横构图，胶片质感",
                           size="2K", watermark=False)
img = r.data[0]
print(r.model, img.size, r.usage.generated_images)
open("cat.jpg", "wb").write(requests.get(img.url, timeout=60).content)

# 5.0 lite：2K 缺省档（2048x2048）
l = client.images.generate(model="doubao-seedream-5.0-lite",
                           prompt="一只橘猫坐在窗台上，胶片质感",
                           size="2K", watermark=False)
open("cat-lite.jpg", "wb").write(requests.get(l.data[0].url, timeout=60).content)

# 多图参考
e = client.images.generate(model="doubao-seedream-5.0-pro",
                           prompt="把第一张图的猫放到第二张图的霓虹街景里",
                           image=["https://example-cdn.com/cat.jpg", "https://example-cdn.com/street.jpg"],
                           size="1280x720")
open("cat-neon.jpg", "wb").write(requests.get(e.data[0].url, timeout=60).content)

4. 计费口径

• 按张计费：以 usage.generated_images 为结算数量，每张固定单价，与 size 档位无关。
• 每个模型一个单价：5.0 pro / 5.0 lite / 5.0 / 4.5 在控制台「模型列表」中各有一张价卡，单价不同（5.0 与 5.0 lite 同价）。
• 请求时预授权冻结，响应返回后按实际生成张数结算。
• 请求被拒（400）或生成失败不计费，预授权自动释放。
• HTTP 200 但 data[] 中没有任何 url / b64_json（例如各条目均为 error）不计费。
• 内容审核拒绝（如 OutputImageSensitiveContentDetected）返回 HTTP 400 并携带上游错误码，不计费、不重试。

常见错误