# 生成图片

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

本文介绍生成图片 API 的输入输出参数，供您使用接口时查阅字段含义。模型依据提示词与参考图生成图片，一次调用同步返回；也可开启流式输出，逐张返回结果。





<Callout type="warn" title="图片链接 24 小时后失效">
  `response_format=url` 时返回的 `data[].url` 为临时地址，**生成后 24 小时内有效**。需长期保存的图片请在有效期内转存至己方存储，勿直接入库或分发给终端用户；也可改用 `response_format=b64_json` 直接获取图片数据。
</Callout>

## 调用流程 [#调用流程]

1. **选择模型**：`model` 填写控制台模型目录中已启用的图片模型 ID。可用的生成场景由模型决定，见[模型能力](/zh-cn/images/ark#模型)。
2. **发起请求**：默认同步返回，全部图片生成完毕后一次性返回 `data[]`；`stream=true` 时逐张返回，见[流式输出](#流式输出)。
3. **取回图片**：`response_format=url` 时从 `data[].url` 下载（24 小时内有效），`b64_json` 时读取 `data[].b64_json`。
4. **核对用量**：`usage.generated_images` 为本次成功生成的张数，即计费依据；`X-Request-Id` 响应头用于问题排查。

## 接口详情 [#接口详情]

<OpenAPIPage document="public" operations="[{&#x22;path&#x22;:&#x22;/api/v3/images/generations&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" examples="examples" />

## 尺寸（size） [#尺寸size]

`size` 有两种写法，**不可混用**：

* **档位词**（如 `1K`、`2K`、`4K`）：在 `prompt` 中以自然语言描述宽高比、形状或用途，由模型确定最终尺寸。
* **宽高像素值**（`<宽>x<高>`，如 `2048x2048`）：需**同时**满足所选模型的总像素区间与宽高比区间 \[1/16, 16]。总像素为宽与高的乘积限制，非对宽或高单独限制。

各模型的取值如下：

| 模型                     | 档位词                     | 默认值         | 总像素区间（宽 × 高）                                   |
| ---------------------- | ----------------------- | ----------- | ---------------------------------------------- |
| Seedream 5.0 pro       | `1K`、`1.5K`、`2K`        | `2K`        | \[921600（`1280x720`）, 4624220]                 |
| Seedream 5.0 pro（图层拆分） | `1K`、`1.5K`、`2K`、`auto` | `auto`      | 仅支持档位词                                         |
| Seedream 5.0 lite      | `2K`、`3K`、`4K`          | `2048x2048` | \[3686400（`2560x1440`）, 16777216（`4096x4096`）] |
| Seedream 4.5           | `2K`、`4K`               | `2048x2048` | \[3686400（`2560x1440`）, 16777216（`4096x4096`）] |
| Seedream 4.0           | `1K`、`2K`、`4K`          | `2048x2048` | \[921600（`1280x720`）, 16777216（`4096x4096`）]   |

档位词对应的常见宽高像素（不限于下列标准值）：

| 档位     | 1:1       | 4:3       | 16:9      | 3:2       | 21:9      |
| ------ | --------- | --------- | --------- | --------- | --------- |
| `1K`   | 1024x1024 | 1152x864  | 1424x800  | 1248x832  | 1568x672  |
| `1.5K` | 1536x1536 | 1792x1344 | 2048x1152 | 1872x1248 | 2352x1008 |
| `2K`   | 2048x2048 | 2304x1728 | 2848x1600 | 2496x1664 | 3136x1344 |
| `3K`   | 3072x3072 | 3456x2592 | 4096x2304 | 3744x2496 | 4704x2016 |
| `4K`   | 4096x4096 | 4704x3520 | 5504x3040 | 4992x3328 | 6240x2656 |

竖版比例（3:4、9:16、2:3）为上表对应行的宽高对调。Seedream 4.0 的 `1K` 略有出入：16:9 为 `1280x720`，21:9 为 `1512x648`。

图层拆分场景下 `size` 仅接受档位词：底图按 `size` 输出并保持输入图的宽高比，各图层分辨率与 `size` 接近、各自保持其在输入图中的宽高比；`auto` 表示按输入图的原始尺寸输出，小于 1K 时按 1K、大于 2K 时按 2K。

<Callout type="info" title="尺寸校验范围">
  本接口仅校验显式宽高的单边像素落在 \[1, 16384] 内，超出返回 400 `InvalidParameter`（`param=size`）。总像素区间与档位词的合法性由模型判定，不合法时返回模型给出的参数错误。
</Callout>

## 流式输出 [#流式输出]

`stream=true` 时响应为 `200 text/event-stream`，响应头另含 `X-Accel-Buffering: no` 与 `X-Request-Id`，每张图片生成完成后即下发一帧。是否支持由所选模型决定：Seedream 5.0 pro 不支持，5.0 lite / 4.5 / 4.0 支持；向不支持的模型传入 `true` 返回 400 `InvalidParameter`（`reasonCode=image_invalid_field`，`param=stream`），该请求不计费。

事件名与分帧结构与火山方舟一致，字段结构见[图片生成流式响应事件](https://docs.volcengine.com/docs/82379/1824137)，形如：

```text
event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","image_index":1,"url":"https://...","size":"2048x2048"}

event: image_generation.completed
data: {"type":"image_generation.completed","usage":{"generated_images":4}}
```

解析时遵循以下约定：

1. **HTTP 状态码恒为 200**。单张图片失败与整次请求失败均在事件中表达，不体现在状态码。仅在流建立之前失败（鉴权、参数校验、内容安全检测等）返回普通 JSON 错误响应；流建立之后的失败以一帧 `event: error` 返回，负载为上述错误结构。
2. **以终局事件判断结束**。收到 `completed` 或 `error` 即为流结束，其后不再有数据帧，包括 `[DONE]` 之类的哨兵；请勿以哨兵作为结束判据。
3. **断开连接不中止本次生成**，已生成的图片照常计费。
4. **计费口径与非流式一致**，按每张成功图片各自的 `size` 定档；流中途中断时按已返回的成功项结算。

## 常见问题 [#常见问题]

### 组图中部分图片生成失败 [#组图中部分图片生成失败]

请求仍返回 200，成功的图片正常返回，失败项在 `data[]` 中携带 `error`，仅对成功生成的图片计费：

```json
{
  "created": 1756000000,
  "model": "doubao-seedream-4-0",
  "data": [
    { "url": "https://...", "size": "2048x2048", "output_format": "png" },
    {
      "error": {
        "code": "OutputImageSensitiveContentDetected",
        "message": "The generated image failed the content safety check."
      }
    }
  ],
  "usage": { "generated_images": 1, "output_tokens": 16384, "total_tokens": 16384 }
}
```

未生成任何图片时，错误返回在顶层 `error`，本次调用不计费。

### 提示词未通过内容安全检测 [#提示词未通过内容安全检测]

请求返回 400，不计费：

```json
{
  "error": {
    "code": "InputTextSensitiveContentDetected",
    "message": "the request was blocked by content moderation. Request id: 021790892668142434549f79b621a35",
    "param": "content",
    "type": "BadRequest",
    "reasonCode": "image_text_blocked_by_moderation",
    "requestId": "021790892668142434549f79b621a35"
  }
}
```

调整提示词后重新提交。

### 请求体超出上限（413） [#请求体超出上限413]

参考图以 Base64 内联时易超出请求体上限（64 MB），返回 413 `InvalidParameter`（`reasonCode=image_request_too_large`）。请将参考图存放至对象存储，改以公网可访问的 URL 传入。

### 请求了模型不支持的能力 [#请求了模型不支持的能力]

组图、图层拆分、流式输出与参考图张数是否可用，由所选模型决定。模型不支持时返回 400 `InvalidParameter`（`reasonCode=image_invalid_field`），`param` 指出对应字段，本次调用不计费。各模型支持情况见[模型能力](/zh-cn/images/ark#模型)。

## 参考文档 [#参考文档]

* [火山方舟图片生成总览](/zh-cn/images/ark)：接入信息、模型能力、计费口径与错误码
* [Seedream 图像创作教程](https://docs.volcengine.com/docs/82379/1824121)（火山方舟）
* [Seedream 4.0-5.0 提示词指南](https://docs.volcengine.com/docs/82379/1829186)（火山方舟）


---

本页对应接口：`POST /api/v3/images/generations`。机器可读的完整 schema：

- 本接口 schema：http://localhost:3000/docs/openapi/operations/generateSeedreamImages.zh.json
- 完整对外 spec（供代码生成工具使用）：http://localhost:3000/docs/openapi/public.zh.json