本文介绍网易云信大模型 API（简称 AIHub）与 Volcengine Seedream 厂商兼容 的图片生成接口的使用说明。

请求说明

AIHub 提供两个入口访问 Seedream 图片生成能力：

入口	URL	说明
AIHub 统一入口	POST https://ai.yunxinapi.com/hub/v1/images/generations	推荐使用，统一协议入口
Volcengine 同协议原生入口	POST https://ai.yunxinapi.com/hub/volcengine/api/v3/images/generations	方便火山原生 HTTP Client 迁移的协议路径别名

• 两个入口复用同一套鉴权、逻辑模型（Logical Model）选路和 Provider 实现。
• /volcengine 路径前缀 不会 强制指定 Provider，仅当 Logical Model 选中 Seedream Candidate 时，才使用本文所述的火山原生请求与响应结构。
• 请勿 将原厂 ARK_API_KEY 发送到 AIHub。

请求参数

Header 参数

参数	必填	说明	示例
Authorization	必填	AIHub API Key Bearer 鉴权	Bearer <AIHUB_API_KEY>
Content-Type	必填	请求体类型	application/json
Accept	流式建议	stream: true 时可显式声明 SSE	text/event-stream
X-AIHub-Affinity-Key	可选	脱敏亲和键，用于请求稳定落到同一路由候选；不要 放入 prompt、图片内容、密钥或个人信息	image-job-42

成功或错误响应会返回 X-AIHub-Request-Id，排障时请记录该值。

Body 参数

参数	类型/位置	必填	说明	示例
model	string，body 顶层	必填	AIHub Logical Model。AIHub 路由到火山上游后，会将成功响应中的 model 字段改写为该 Logical Model	"doubao-seedream-5-0-lite"
prompt	string，body 顶层	必填	中英文提示词。官方建议不超过 300 个汉字或 600 个英文单词	"生成一张白色背景的极简产品海报，主体为红色自行车，横版 16:9。"
image	string 或 string[]	可选	参考图片 URL 或 Data URL。可传单图或多图	["https://example.com/bike.png"]
size	string	可选	分辨率档位或自定义 宽x高，两种形式 不能混用	"2K" 或 "2048x2048"
optimize_prompt_options	object	可选	提示词优化配置	{"mode":"fast"}
optimize_prompt_options.mode	string	可选，默认 standard	standard：优先质量；fast：优先时延	"fast"
output_format	string	可选，默认 jpeg	输出文件格式：png、jpeg；仅 Seedream 5.0 pro / lite 支持	"png"
response_format	string	可选，默认 url	url：返回下载地址（24 小时内有效）；b64_json：返回 Base64 数据	"url"
sequential_image_generation	string	可选，默认 disabled	disabled：仅生成一张；auto：由模型判断是否生成组图	"auto"
sequential_image_generation_options	object	条件可选	组图配置，仅在 sequential_image_generation: "auto" 时生效	{"max_images":4}
sequential_image_generation_options.max_images	integer	可选，默认 15	最多生成图片数，范围 [1, 15]	4
stream	boolean	可选，默认 false	false：等待全部图片完成后返回 JSON；true：通过 SSE 逐张返回	true
tools	object[]	可选	模型工具列表，目前仅 Seedream 5.0 lite 支持联网搜索	[{"type":"web_search"}]
tools[].type	string	工具项必填	当前仅支持 web_search	"web_search"
watermark	boolean	可选，默认 true	true：添加“AI 生成”水印；false：不添加	false

Seedream 使用火山原生图片参数。不要 将 OpenAI Images 模型的 n、quality、style、background 或 output_compression 当作 Seedream 参数发送。需要多张输出时，请使用 sequential_image_generation 及其配置。

请求示例

文生图（非流式）

以下示例使用 AIHub 统一入口和 Seedream 5.0 pro 生成单图：

bashcurl -X POST "https://ai.yunxinapi.com/hub/v1/images/generations" \
  -H "Authorization: Bearer <AIHUB_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "白色摄影棚中的红色自行车和鲜花，产品摄影，高细节，横版 3:2。",
    "size": "2K",
    "output_format": "jpeg",
    "response_format": "url",
    "watermark": false,
    "stream": false
  }'

多图生组图（流式）

以下示例使用 Volcengine 同协议入口。Seedream 5.0 lite 最多返回 3 张图，并允许模型按需联网搜索：

示例中的 example.com 图片地址仅为占位符，调用前 必须 替换为火山上游可访问的真实图片 URL。

bashcurl --no-buffer -X POST \
  "https://ai.yunxinapi.com/hub/volcengine/api/v3/images/generations" \
  -H "Authorization: Bearer <AIHUB_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "doubao-seedream-5-0-lite",
    "prompt": "融合两张参考图，生成一组统一视觉语言的产品发布海报。",
    "image": [
      "https://example.com/product.png",
      "https://example.com/style.jpg"
    ],
    "size": "2K",
    "output_format": "png",
    "response_format": "url",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 3
    },
    "tools": [
      {"type": "web_search"}
    ],
    "watermark": false,
    "stream": true
  }'

非流式响应

响应参数

参数	类型/位置	说明
created	integer，顶层	请求创建时间的 Unix 秒级时间戳
model	string，顶层	AIHub 返回请求中的 Logical Model，不 暴露内部上游模型映射
data	object[]，顶层	图像结果数组；组图时每项代表一张成功图片或一次单图失败
data[].url	string	response_format: "url" 时返回，链接生成后 24 小时内有效
data[].b64_json	string	response_format: "b64_json" 时返回
data[].size	string	实际图像尺寸，格式为 宽x高
data[].output_format	string	实际输出格式（png / jpeg）。火山官方当前仅 Seedream 5.0 pro 明确返回该字段；5.0 lite 虽支持请求 output_format，但调用方 不能假设 响应中必有此字段
data[].error	object	当前图片生成失败时返回，不表示 数组中其他图片均失败
data[].error.code	string	单图失败错误码
data[].error.message	string	单图失败说明
tools	object[]，顶层	实际调用的工具；目前仅 5.0 lite 的 web_search，未调用时可能省略
tools[].type	string	工具类型，当前为 web_search
usage	object，顶层	本次图片生成用量
usage.generated_images	integer	成功生成图片数，不包含 失败图片
usage.input_images	integer	输入图片数；火山官方当前仅 5.0 pro 明确支持返回，其他模型可能省略
usage.output_tokens	integer	输出图片 Token 数，基于输出图片总像素计算
usage.total_tokens	integer	总 Token 数；当前 不计算 输入 Token，通常等于 output_tokens
usage.tool_usage.web_search	integer	实际联网搜索次数；仅 5.0 lite 开启工具时可能返回，0 表示未搜索

成功响应示例

json{
  "model": "doubao-seedream-5-0-pro",
  "created": 1785800747,
  "data": [
    {
      "url": "https://example.com/generated-image.jpeg",
      "size": "2496x1664",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "input_images": 0,
    "generated_images": 1,
    "output_tokens": 16224,
    "total_tokens": 16224
  }
}

组图部分失败：组图允许部分成功。某张图审核不通过时，响应可同时包含其他成功图片和该图片的 data[].error；若发生会终止后续生成的内部错误，实际返回数量可能少于 max_images。

流式响应

stream: true 时响应 Content-Type 为 text/event-stream。每个 SSE Frame 的 event 表示事件名，data 为 JSON 对象。

5.0 pro 不支持流式；对不支持流式的模型发起请求时，以火山上游返回的错误为准。

SSE 事件

事件	含义	主要字段
image_generation.partial_succeeded	一张图片生成成功	type、model、created、image_index、url / b64_json、size
image_generation.partial_failed	一张图片生成失败，其他图片仍可能继续	type、model、created、image_index、error.code、error.message
image_generation.completed	本次生成结束并返回汇总	type、model、created、tools、usage
error	整个请求失败	error.code、error.message

• image_index 从 0 开始。
• AIHub 会将可解析 SSE data 顶层的 model 改回请求中的 Logical Model，其他原生事件字段保持不变。

流式响应示例

textevent: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","model":"doubao-seedream-5-0-lite","created":1785800835,"image_index":0,"url":"https://example.com/image-0.jpeg","size":"2048x2048"}

event: image_generation.partial_failed
data: {"type":"image_generation.partial_failed","model":"doubao-seedream-5-0-lite","created":1785800836,"image_index":1,"error":{"code":"OutputImageSensitiveContentDetected","message":"The output image may contain sensitive information."}}

event: image_generation.completed
data: {"type":"image_generation.completed","model":"doubao-seedream-5-0-lite","created":1785800837,"usage":{"generated_images":1,"output_tokens":16384,"total_tokens":16384}}

• 调用方应按 SSE Frame 增量解析，不要假设 一次网络读取恰好对应一个事件。
• image_generation.completed 和整体 error 均为 终止事件，收到后应停止读取并完成本次调用。
• image_generation.partial_failed 仅表示单图失败，不是 整体终止。
• 客户端中途断开时，未收到的图片和最终 Usage 不能 视为已交付。

限制说明

参考图片限制

image 支持公网可访问 URL，也支持以下 Data URL 形式：

textdata:image/png;base64,<BASE64_IMAGE>

Data URL 中的图片格式名应使用 小写。

每张输入图片必须同时满足以下限制：

限制项	要求
格式	jpeg、png、webp、bmp、tiff、gif、heic、heif
宽高比（宽 / 高）	[1/16, 16]
宽、高	均 > 14 px
文件大小	≤ 30 MB
总像素	≤ 36,000,000 px

多图输入数量限制：

模型	最多输入图片数
Seedream 5.0 pro	10 张
Seedream 5.0 lite / 4.5 / 4.0	14 张

• 调用方应保证 URL 在模型读取期间持续可访问，避免 使用带长期凭证的私有 URL。
• 图片 URL、Data URL 和 Base64 图片正文可能包含敏感内容。不要 将完整请求体、响应体、SSE Frame、Base64 字符串或签名 URL 写入应用日志、重试日志和异常上报。需要留存图片时，应及时转存到有访问控制的业务存储，并仅记录脱敏资源 ID。

输出尺寸限制

模型系列	分辨率档位	省略 size 时	自定义尺寸总像素范围	宽高比范围
Seedream 5.0 pro	1K、2K	2K	[921,600, 4,624,220]	[1/16, 16]
Seedream 5.0 lite	2K、3K、4K	2048x2048	[3,686,400, 16,777,216]	[1/16, 16]
Seedream 4.5	2K、4K	2048x2048	[3,686,400, 16,777,216]	[1/16, 16]
Seedream 4.0	1K、2K、4K	2048x2048	[921,600, 16,777,216]	[1/16, 16]

档位说明：

• 使用档位时，可在 Prompt 中描述比例、形状或用途，模型据此选择实际宽高。
• 档位名称 不保证 固定对应某一宽高值。例如 Seedream 5.0 lite 的 2K 常见输出包括 2048x2048、2304x1728、2848x1600。

自定义尺寸示例：

• 5.0 pro：2048x1024 有效；512x512 总像素不足。
• 5.0 lite/4.5：3750x1250 有效；1500x1500 总像素不足。
• 4.0：1600x600 有效；800x800 总像素不足。

AIHub 大小限制

火山官方的单图限制 不等于 AIHub 对整个 HTTP 消息的限制。两个入口还受以下边界约束：

场景	AIHub 限制	影响与建议
JSON / Provider-native 请求体	默认 32 MiB	Base64 编码通常比原文件大约 1/3；一张接近 30 MB 的图片编码后即可超限。大图或多图优先使用可访问 URL。
非流式成功响应	16 MiB	高分辨率 b64_json（尤其 PNG）可能超限并返回 upstream_body_malformed。大图优先使用 response_format: "url"。
流式成功事件	单个 SSE Frame 8 MiB	4K + PNG + b64_json 等组合可能超限并导致 502 或流中途失败。高分辨率输出不要使用流式 Base64。

32 MiB 为默认部署值，以当前环境实际限制为准。16 MiB 非流式响应上限和 8 MiB SSE 单帧上限为当前 AIHub Provider 的兼容边界。

AIHub 行为与错误边界

行为	说明
Logical Model 改写	请求中的 model 为 AIHub Logical Model。非流式成功响应顶层 model 和 SSE data 顶层 model 会改回请求值
响应结构保留	Seedream 成功响应保留火山原生 JSON 或 SSE 结构，不 包装为 provider_result，也 不 转换为其他厂商的字段语义
入口支持	两个 AIHub 入口均支持 Seedream Provider 的 Unary 和 Stream 调用路径；模型是否支持流式按能力矩阵判断
整体错误	请求级鉴权、路由、限流及响应提交前发现的整体生成错误，使用 AIHub 统一错误响应
图片级错误	非流式 data[].error 和 SSE 开始输出后的 error 事件，保留图片级或火山原生语义
URL 有效期	结果 URL 仅 24 小时有效，应视为临时访问凭证。业务方应及时下载或转存，不要 公开、完整记录或将其作为长期资源 ID
超时处理	图片生成可能耗时较长。客户端超时应覆盖排队和完整生成时间；流式调用需正确处理断流、取消、单图失败和未收到 completed 事件的情况

关于 SSE error 事件：

• 已经开始输出后的 SSE error.error.message 为火山上游返回的 不可信文本。
• 程序应按已知 error.code 处理，并为未知 Code 提供兜底。
• 展示 Message 前 必须转义，写日志时 必须截断和脱敏，不要 将原文直接暴露给终端用户。

整体请求失败示例：

整体请求在响应提交前失败时，返回 AIHub 统一错误结构：

json{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_body",
    "message": "invalid request body",
    "request_id": "req_abc123"
  }
}

调用方应按稳定的 error.code 分支处理，用 error.request_id 或响应 Header X-AIHub-Request-Id 排障，不要 匹配 message 文案。