# 火山方舟

URL: http://localhost:3000/docs/zh-cn/images/ark

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



## 接入信息 [#接入信息]

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

接入地址（Server URL）见[生成图片](/zh-cn/images/ark/generateSeedreamImages#接口详情)页接口面板顶部的服务器选择框。

## 鉴权 [#鉴权]

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

```text
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` 取整）。

## 错误 [#错误]

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

```json
{
  "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]

`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 传入。

## 官方文档 [#官方文档]

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

* [Seedream 图像创作教程](https://docs.volcengine.com/docs/82379/1824121)（组图输出、流式输出等场景示例）
* [图片生成流式响应事件](https://docs.volcengine.com/docs/82379/1824137)
* [Seedream 4.0-5.0 提示词指南](https://docs.volcengine.com/docs/82379/1829186)
* [错误码](https://docs.volcengine.com/docs/82379/1299023)