火山方舟

图片生成接口的参数集对齐火山方舟 Ark images/generations，支持文生图、图生图、组图、图层拆分与流式输出。本文介绍接入信息、鉴权、模型能力、计费口径与错误码。

接入信息

项	值
请求方式	`POST`
请求路径	`/api/v3/images/generations`
内容类型	`application/json`
鉴权	`Authorization: Bearer <API Key>`
请求体上限	64 MB，超出返回 413
响应头	每个响应均返回 `X-Request-Id`；流式调用随响应头一并返回

接入地址（Server URL）见生成图片页接口面板顶部的服务器选择框。

鉴权

在控制台创建 API Key，置于 Authorization 请求头：

Authorization: Bearer <API Key>

API Key 缺失或无效：401 AuthenticationError。
无权调用该模型：403 AccessDenied。

模型

model 取值为本平台的模型 ID，即控制台模型目录中已启用的图片模型；响应中的 model 与请求一致。

各模型支持的能力如下。请求中包含所选模型不支持的能力时返回 400，本次调用不计费。

能力	Seedream 5.0 pro	Seedream 5.0 lite / 4.5 / 4.0
参考图（`image`）	最多 10 张	最多 14 张
组图（`sequential_image_generation=auto`）	不支持	支持，输入参考图与生成图片合计不超过 15 张
图层拆分（`layer_decomposition=true`）	支持，1 张底图 + 最多 16 个图层	不支持
流式（`stream=true`）	不支持	支持

生成场景

场景	关键入参	输出
文生图	`prompt`	单张图片
单图生图	`prompt` + `image`（1 张）	单张图片
多图生图	`prompt` + `image`（多张）	单张图片
组图	`prompt` + `sequential_image_generation=auto`	一组内容关联的图片
图层拆分	`image`（恰好 1 张）+ `layer_decomposition=true`	1 张底图 + 多个带透明通道的 PNG 图层

取回图片

response_format=url（默认）：data[].url 为图片下载链接，生成后 24 小时内有效，过期失效。需长期保存的图片请在有效期内转存至己方存储，勿直接入库或分发给终端用户。
response_format=b64_json：data[].b64_json 返回图片的 Base64 编码，响应体随图片尺寸与张数增大。

计费

按成功生成的图片张数计费，单价按每张图片各自的 size 档位计算；输入参考图另计附加费。
调用期间按本次可能生成的最大张数预占额度，结算后释放差额。
组图中部分图片生成失败时请求仍返回 200，仅对成功生成的图片计费，失败项在 data[].error 中返回。
未生成任何图片（返回顶层 error）时不计费。
联网搜索（tools）不计费，调用次数见 usage.tool_usage.web_search。
流式与非流式计费口径一致。断开连接不中止本次生成，已生成的图片照常计费。

用量信息见响应的 usage：generated_images（成功生成张数）、input_images（输入图片张数，部分模型返回）、output_tokens 与 total_tokens（按 sum(图片长 × 图片宽) / 256 取整）。

错误

失败响应统一为以下结构：

{
  "error": {
    "code": "InvalidParameter",
    "message": "stream: not supported by this model. Request id: 021790892668142434549f79b621a35",
    "param": "stream",
    "type": "BadRequest",
    "reasonCode": "image_invalid_field",
    "requestId": "021790892668142434549f79b621a35"
  }
}

param 为触发错误的参数名，不回显参数值。requestId 与响应头 X-Request-Id 一致，反馈问题时请一并提供。

错误码

HTTP	`code`	含义
400	`InvalidParameter`	参数不合法。本接口校验的字段取值有误时附带 `reasonCode`（见下表），其余参数错误返回模型给出的错误码
400	`InputTextSensitiveContentDetected`	提示词未通过内容安全检测（`reasonCode=image_text_blocked_by_moderation`），不计费
401	`AuthenticationError`	API Key 缺失或无效
403	`AccessDenied`	该模型对本次调用不可用：未启用、未对本账号开放、不在该 API Key 的模型范围内，或非图片模型
403	`AccountOverdueError`	额度不足
403	`OperationDenied.ServiceNotOpen`	未开通该能力
404	`ResourceNotFound`	`model` 指定的模型 ID 不存在
413	`InvalidParameter`	请求体超出上限（`reasonCode=image_request_too_large`），参考图请改以 URL 传入
429	`QuotaExceeded`	触发额度或频率限制，请稍后重试
500	`InternalServiceError`	服务内部错误，请携带 `requestId` 反馈

内容安全相关的错误码（如 OutputImageSensitiveContentDetected、InputImageSensitiveContentDetected）与火山方舟一致。

`reasonCode`

reasonCode 用于区分同一 code 下的不同原因：

`reasonCode`	含义
`image_invalid_field`	本接口校验的字段取值无法解析，或所选模型不支持该取值；`param` 指出对应字段
`image_text_blocked_by_moderation`	提示词未通过内容安全检测
`image_request_too_large`	请求体超出上限

参数校验

本接口校验以下字段：model、prompt（存在时须为字符串）、image（张数）、size、stream、layer_decomposition、sequential_image_generation 及 sequential_image_generation_options.max_images。

其余字段按原样提交给模型，取值是否合法以模型返回为准；本文未列出的字段同样如此。本接口不定义终端用户标识字段（safety_identifier / user）。

与火山方舟的差异

按火山方舟官方文档接入时，注意以下差异：

model 使用本平台的模型 ID，不接受火山型号名或 Endpoint ID。
所选模型不支持的能力（组图、图层拆分、流式、参考图张数超限）返回 400。
内容安全相关的错误码保持一致，其余错误统一为本接口的错误码；触发限流返回 429 QuotaExceeded。
响应仅包含 X-Request-Id 一个自定义响应头。
请求体存在大小上限，参考图建议以 URL 传入。

官方文档

本接口的参数集沿用火山方舟图片生成，字段语义的完整说明见：

火山方舟

本页目录