> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wengaocloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 火山 Seedream 生图

> 使用 `/volcengine/v3/images/generations` 调用 Seedream 图片生成模型。

`/volcengine/v3/images/generations` 用于调用 Seedream 图片生成模型，支持同步返回，也支持部分模型的流式返回。

<Info>
  * 公网路径：`POST /volcengine/v3/images/generations`
  * 请求体：使用 JSON
  * 返回模式：同步 JSON，或模型支持时返回 `text/event-stream`
  * 不提供异步任务模式
</Info>

## 当前接入模型

下表列出当前平台已接入的 Seedream 5.0 模型。真实可见性以 `/v1/models` 和你的控制台配置为准。

| 模型                                | 典型用途         | 同步 JSON | SSE 流式    | 备注                                             |
| --------------------------------- | ------------ | ------- | --------- | ---------------------------------------------- |
| `doubao-seedream-5-0-lite-260128` | 文生图、组图、参考图生成 | 支持      | 支持        | 支持 `tools`、`sequential_image_generation` 等扩展字段 |
| `doubao-seedream-5-0-pro-260628`  | 高质量单张或多参考图生成 | 支持      | 以实际模型能力为准 | 部分场景下不支持 `stream`                              |

## 请求示例

### 同步文生图

```bash theme={null}
curl -X POST "https://xxx.wengaocloud.com/volcengine/v3/images/generations" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-lite-260128",
    "prompt": "一朵七色花，通透花瓣，纯色背景，质感细腻",
    "size": "1024x1024",
    "response_format": "url",
    "output_format": "png",
    "watermark": false
  }'
```

### 参考图生成

```bash theme={null}
curl -X POST "https://xxx.wengaocloud.com/volcengine/v3/images/generations" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "融合两张参考图的构图与服装风格，保留电影感布光",
    "image": [
      "https://example.com/reference-a.png",
      "https://example.com/reference-b.png"
    ],
    "size": "2048x2048",
    "response_format": "url",
    "optimize_prompt_options": {
      "mode": "standard"
    }
  }'
```

### 流式组图

模型开启流式能力后，可以通过 `stream=true` 接收图片事件流：

```bash theme={null}
curl -N -X POST "https://xxx.wengaocloud.com/volcengine/v3/images/generations" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-lite-260128",
    "prompt": "同一位动漫女孩，连续两张表情变化，画风一致",
    "stream": true,
    "response_format": "b64_json",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 2
    }
  }'
```

典型响应：

```text theme={null}
data: {"type":"image_generation.partial_succeeded","image_index":0,"b64_json":"...","size":"1024x1024"}

data: {"type":"image_generation.partial_succeeded","image_index":1,"b64_json":"...","size":"1024x1024"}

data: {"type":"image_generation.completed","data":[{"size":"1024x1024","b64_json":"..."},{"size":"1024x1024","b64_json":"..."}]}

data: [DONE]
```

## 支持的请求字段

当前文档覆盖的常用请求字段如下：

| 字段                                               | 类型                 | 说明                                             |
| ------------------------------------------------ | ------------------ | ---------------------------------------------- |
| `model`                                          | string             | 要调用的模型名称                                       |
| `prompt`                                         | string             | 生成提示词，必填                                       |
| `image`                                          | string 或 string\[] | 参考图 URL 或 Base64 数据；是否收费取决于配置的输入图价格            |
| `size`                                           | string             | 输出尺寸，例如 `1024x1024`、`2048x2048`                |
| `seed`                                           | integer            | 随机种子                                           |
| `guidance_scale`                                 | number             | 提示词引导强度                                        |
| `response_format`                                | string             | 建议使用 `url` 或 `b64_json`                        |
| `output_format`                                  | string             | 常见值 `jpeg`、`png`、`webp`                        |
| `watermark`                                      | boolean            | 是否要求带水印输出                                      |
| `sequential_image_generation`                    | string             | 目前平台按官方语义透传，常见值 `auto`                         |
| `sequential_image_generation_options.max_images` | integer            | 组图上限；仅在 `sequential_image_generation=auto` 时使用 |
| `stream`                                         | boolean            | 为 `true` 时请求 SSE；模型未开通流式会返回 400                |
| `tools`                                          | array              | 工具数组，是否支持取决于具体模型                               |
| `optimize_prompt_options`                        | object             | 官方提示词优化配置，例如 `{"mode":"standard"}`             |

<Note>
  这条路径不会接受 OpenAI 风格的 `n`。如果需要组图，请使用 `sequential_image_generation=auto` 和 `sequential_image_generation_options.max_images`。
</Note>

## 计费口径

该接口按图片计费，但不是简单“按请求参数固定扣费”。

1. 冻结阶段按请求预估。
2. 结算阶段按每张实际响应图片的尺寸结算。
3. 输入图与输出图分开计价、分开记日志。

也就是说：

* 如果请求里带了 `image`，公式里会单独展示输入图费用。
* 如果返回图片的实际尺寸高于请求预期，会按实际响应尺寸匹配价格档位。
* 如果 `sequential_image_generation=auto` 但没显式给 `max_images`，系统会按可生成张数预估冻结金额。

示例公式可能长这样：

```text theme={null}
输入图：2 张 * ¥0.020000/张 = ¥0.04
输出图：1 张 * ¥0.100000/张 = ¥0.10
合计：¥0.14
```

<Tip>
  生产对账时，建议同时保存请求返回的 `request_id` 和完整响应体。
</Tip>