Seedream

官方协议文档：图片生成 API（火山引擎方舟）。本页字段与官方文档逐项对齐，网关侧的差异集中列在文末「与官方文档的差异」小节；响应字段说明见官方图片生成流式响应事件。

模型与档位

• 上述模型走同一入口 POST /api/v3/images/generations，能力均为文生图、图生图（单图 / 多图参考），必填 model、prompt。组图（sequential_image_generation: "auto"）仅 5.0 lite / 5.0 / 4.5 / 4.0 支持。
• doubao-seedream-5.0 是 doubao-seedream-5.0-lite 的别名：方舟没有独立的 5.0 模型，二者档位与单价完全一致。
• 各模型支持的档位不完全相同，上表只列常用值；完整取值范围以方舟官方文档为准。表外档位会在创建时被拒（HTTP 400），不渲染、不计费。
• 5.0 pro 的 1.5K 与 1K 同价（方舟定价），且只有部分供应商能出该档位，可用线路少于其他档位。
• 入口可达性以模型详情页的协议列表为准。 doubao-seedream-4.0 同时提供 Ark 原生入口（本页）与 OpenAI 兼容入口（POST /v1/images/generations，见下文「OpenAI 兼容入口」）；5.0 / 5.0 lite / 5.0 pro 目前只经 OpenAI 兼容入口提供，见图像生成（OpenAI 兼容）。在未开放的入口上调用会返回 400 model_protocol_not_offered。

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

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

1. 创建图像

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

文生图（4.0）

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

文生图（5.0 pro）

curl https://api.modelgo.ai/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.ai/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.ai/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"
  }'

组图（4.0）

组图由 sequential_image_generation: "auto" 开启，实际张数由模型根据提示词判断，上限由 max_images 约束；具体上限以官方文档为准。

curl https://api.modelgo.ai/api/v3/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0",
    "prompt": "生成 4 张不同风格的柴犬海报：赛博朋克、水彩、极简、复古胶片",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {"max_images": 4}
  }'

例如：请求 4 张时 data[] 返回 4 张图，usage.generated_images = 4，按 4 × 单价结算。

OpenAI 兼容入口

doubao-seedream-4.0 同时提供 OpenAI 兼容入口 POST https://api.modelgo.ai/v1/images/generations。请求体沿用方舟官方字段原样转发，响应也是官方形状，计费规则与原生入口完全一致（见「计费口径」）；方舟官方 SDK 之外的 OpenAI SDK / 客户端可直接使用。

curl https://api.modelgo.ai/v1/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4.0",
    "prompt": "生成 4 张不同风格的柴犬海报：赛博朋克、水彩、极简、复古胶片",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {"max_images": 4}
  }'

• n 必须省略或为 1：方舟 Images API 没有 n，n ≥ 2 会在创建时被拒（HTTP 400）。要一次出多张请用 sequential_image_generation: "auto"。
• 组图：与原生入口相同，sequential_image_generation + sequential_image_generation_options.max_images；例如请求 4 张会返回 4 张，按 4 × 单价结算。
• 图生图 / 多图参考：用 JSON 的 image 字段（与官方一致，URL 或 base64），不要用 multipart 的 /v1/images/edits —— 该模型当前未开放这个入口，请求会返回 400 model_protocol_not_offered。
• 其余字段（size、watermark、response_format、stream 等）的限制与原生入口相同，见「参数说明」与「与官方文档的差异」。

响应结构

{
  "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-4-0-250828）。
• response_format 缺省 url，链接 24 小时内有效，请及时下载，不要持久化该 URL。
• response_format: "b64_json" 时 data[].b64_json 直接给出 base64 图像。
• data[].size 是实际输出像素。data[].output_format（编码格式）与 usage.input_images 只由 5.0 pro / 5.0 flash 返回，4.0 / 4.5 / 5.0 lite 的响应中没有这两个字段。
• usage.output_tokens / total_tokens 为上游回显的参考值，不参与计费；结算只看 usage.generated_images。
• 组图场景中某张图失败时，该条目为 {"error": {...}}，其余条目照常返回；只有成功生成的图片计费。
• 5.0 lite 开启 tools: [{"type":"web_search"}] 时，搜索次数在 usage.tool_usage.web_search 回显，并单独按加价项计费。

保存到文件：

curl -s https://api.modelgo.ai/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. 参数说明

字段名、类型、默认值与模型支持范围均以官方文档为准；下表在官方字段之外标注了 ModelGo 当前的实际行为。

• 请求体中出现上表之外的字段 → 400，不会被忽略（这条比官方更严：官方对未知字段不保证报错）。
• 按可交付档位选路。 网关优先选择能按所声明 size 交付的供应商；若没有供应商声明该档位，仍把请求交给可用供应商，由其最终裁决（不支持时返回 400）。

分辨率档位

size 可传档位（如 1K / 2K / 4K）或 宽x高（如 1280x720、2048x2048）。档位决定总像素量级，精确宽高由构图提示或显式 WxH 决定。各模型的可用档位与像素上下限不同，以上表常用值为例，完整约束以方舟官方文档为准；越界会返回 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.ai/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 档位无关。组图一次生成 N 张即按 N × 单价结算。
• 两个入口计价一致：Ark 原生入口与 OpenAI 兼容入口读的是同一份计量（image_generation_calls = 实际生成张数），同一请求走哪个入口实收相同。
• 每个模型一个单价：4.0 / 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 并携带上游错误码，不计费、不重试。

5. 与官方文档的差异

以下差异是有意的网关行为，其余字段、取值范围、默认值与官方文档一致（与官方文档对齐）。

常见错误