`POST https://ark.cn-beijing.volces.com/api/v3/images/generations` 本文介绍 Doubao Seedream 5.0 pro、Doubao Seedream 5.0 lite、Doubao Seedream 4.5 及 Doubao Seedream 4.0 图片生成模型的调用 API，包括输入输出参数、取值范围、注意事项等信息，供您使用接口时查阅字段含义。 **模型能力** * **Seedream 5.0 pro^new** * 生成单图（不支持配置 `sequential_image_generation`） * 多图生图：输入多张参考图片（2\-10）+ 文本提示词，生成单张图片。 * 单图生图：输入单张参考图片 + 文本提示词，生成单张图片。 * 文生图：输入文本提示词，生成单张图片。 * 交互编辑： * 支持通过坐标、框选、箭头等多种方式指定编辑位置，精准编辑图片。 * 暂不支持组图生成、联网搜索、流式输出。 * **Seedream 5.0 lite** 、 **Seedream 4.5 / 4.0** * 生成组图（组图：基于您输入的内容，生成的一组内容关联的图片；需配置 `sequential_image_generation` 为 `auto`） * 多图生组图：输入多张参考图片（2\-14）+ 文本提示词，生成一组内容关联的图片（输入的参考图数量 + 最终生成的图片数量 ≤ 15 张）。 * 单图生组图：输入单张参考图片 + 文本提示词，生成一组内容关联的图片（最多生成 14 张图片）。 * 文生组图：输入文本提示词，生成一组内容关联的图片（最多生成 15 张图片）。 * 生成单图（配置 `sequential_image_generation` 为 `disabled`） * 多图生图：输入多张参考图片（2\-14）+ 文本提示词，生成单张图片。 * 单图生图：输入单张参考图片 + 文本提示词，生成单张图片。 * 文生图：输入文本提示词，生成单张图片。 ## 鉴权本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](https://docs.volcengine.com/docs/82379/1298459)。 * API Key 鉴权，请在 [API Key 管理](https://console.volcengine.com/ark/region:cn-beijing/apiKey) 页面，获取长效 API Key。 --- ## 请求参数 ### Body 参数 **model** `string` `必选` | 模型 ID 您需要调用的模型的 ID（Model ID），[开通模型服务](https://console.volcengine.com/ark/region:cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false)，并 [查询 Model ID](https://docs.volcengine.com/docs/82379/1330310#9df4d9fd)。您也可通过 Endpoint ID 来调用模型，获得限流、计费类型（前付费 / 后付费）、运行状态查询、监控、安全等高级能力，可参考 [获取 Endpoint ID](https://docs.volcengine.com/docs/82379/1099522)。 **prompt** `string` `必选` | 提示词用于生成图像的提示词，支持中英文。（查看提示词指南：[Seedream 4.0-5.0 提示词指南](https://docs.volcengine.com/docs/82379/1829186)）建议不超过 300 个汉字或 600 个英文单词。字数过多信息容易分散，模型可能因此忽略细节，只关注重点，造成图片缺失部分元素。 **image** `string / string[]` | 参考图片输入的图片信息，支持 URL 或 Base64 编码。支持单图或多图输入（[查看多图融合示例](https://docs.volcengine.com/docs/82379/1824121#4a35e28f)）。 * 图片 URL：请确保图片 URL 可被访问。 * Base64 编码：请遵循此格式 `data:image/<图片格式>;base64,`。注意 `<图片格式>` 需小写，如 `data:image/png;base64,`。

说明

传入单张图片要求：

图片格式：jpeg、png、webp、bmp、tiff、gif、heic、heif

宽高比（宽 / 高）范围：[1/16, 16]

宽高长度（px）\> 14

大小：不超过 30MB

总像素：不超过 6000x6000=36000000 px（对单张图宽度和高度的像素乘积限制，而不是对宽度或高度的单独值进行限制）

Seedream 5.0 pro 最多支持传入 10 张参考图；Seedream 5.0 lite / 4.5 / 4.0 最多支持传入 14 张参考图。

**size** `string` | 图像尺寸指定生成图像的尺寸信息，支持指定分辨率档位（如 `2K`）或指定宽高像素值（如 `2048x2048`）两种方式，不可混用。不同模型的可选分辨率、默认值、总像素取值范围、宽高比取值范围不同，请展开以下各模型对应说明查看。 **Seedream 5.0 pro** 支持以下两种方式，不可混用： * 方式 1（推荐）：指定分辨率档位，并在 prompt 中用自然语言描述图片宽高比、图片形状或图片用途，最终由模型判断生成图片的大小。 * 默认值：`2K` * 可选值：`1K`、`1.5K`、`2K`

说明

1.5K 与 1K 价格相同，且图片生成效果更优。

* 方式 2：指定宽高像素值（`宽x高`）。 * 总像素取值范围：[`1280x720`（921600）, `2048x2048x1.1025`（4624220）] * 宽高比取值范围：[1/16, 16]

说明

采用方式 2 时，需同时满足总像素取值范围和宽高比取值范围。其中，总像素是对单张图宽度和高度的像素乘积限制，而不是对宽度或高度的单独值进行限制。

有效示例 ：2048x1024。总像素值 2048x1024=2097152，符合 [921600, 4624220] 的区间要求；宽高比 2048/1024=2，符合 [1/16, 16] 的区间要求，故该示例值有效。

无效示例 ：512x512。总像素值 512x512=262144，未达到 921600 的最低要求，故该示例值无效。

使用方式 1 时，模型实际映射的宽高像素参考值（不限于以下标准值，仅列常见）： |分辨率 |宽高比 |宽高像素值 | |---|---|---| |1K |1:1 |1024x1024 | | |4:3 |1152x864 | | |3:4 |864x1152 | | |16:9 |1424x800 | | |9:16 |800x1424 | | |3:2 |1248x832 | | |2:3 |832x1248 | | |21:9 |1568x672 | |1.5K |1:1 |1536x1536 | | |4:3 |1792x1344 | | |3:4 |1344x1792 | | |16:9 |2048x1152 | | |9:16 |1152x2048 | | |3:2 |1872x1248 | | |2:3 |1248x1872 | | |21:9 |2352x1008 | |2K |1:1 |2048x2048 | | |4:3 |2368x1776 | | |3:4 |1776x2368 | | |16:9 |2816x1584 | | |9:16 |1584x2816 | | |3:2 |2496x1664 | | |2:3 |1664x2496 | | |21:9 |3136x1344 | **Seedream 5.0 lite** 支持以下两种方式，不可混用： * 方式 1：指定分辨率，并在 prompt 中用自然语言描述图片宽高比、图片形状或图片用途，最终由模型判断生成图片的大小。 * 可选值：`2K`、`3K`、`4K` * 方式 2：指定生成图像的宽高像素值。 * 默认值：`2048x2048` * 总像素取值范围：[`2560x1440`（3686400）, `4096x4096`（16777216）] * 宽高比取值范围：[1/16, 16]

说明

有效示例 ：3750x1250。总像素值 3750x1250=4687500，符合 [3686400, 16777216] 的区间要求；宽高比 3750/1250=3，符合 [1/16, 16] 的区间要求，故该示例值有效。

无效示例 ：1500x1500。总像素值 1500x1500=2250000，未达到 3686400 的最低要求；宽高 1500/1500=1，虽符合 [1/16, 16] 的区间要求，但未同时满足两项限制，故该示例值无效。

采用方式 1 时，模型实际映射的宽高像素参考值： |分辨率 |宽高比 |宽高像素值 | |---|---|---| |2K |1:1 |2048x2048 | | |4:3 |2304x1728 | | |3:4 |1728x2304 | | |16:9 |2848x1600 | | |9:16 |1600x2848 | | |3:2 |2496x1664 | | |2:3 |1664x2496 | | |21:9 |3136x1344 | |3K |1:1 |3072x3072 | | |4:3 |3456x2592 | | |3:4 |2592x3456 | | |16:9 |4096x2304 | | |9:16 |2304x4096 | | |3:2 |3744x2496 | | |2:3 |2496x3744 | | |21:9 |4704x2016 | |4K |1:1 |4096x4096 | | |4:3 |4704x3520 | | |3:4 |3520x4704 | | |16:9 |5504x3040 | | |9:16 |3040x5504 | | |3:2 |4992x3328 | | |2:3 |3328x4992 | | |21:9 |6240x2656 | **Seedream 4.5** 支持以下两种方式，不可混用： * 方式 1：指定分辨率，并在 prompt 中用自然语言描述图片宽高比、图片形状或图片用途，最终由模型判断生成图片的大小。 * 可选值：`2K`、`4K` * 方式 2：指定生成图像的宽高像素值。 * 默认值：`2048x2048` * 总像素取值范围：[`2560x1440`（3686400）, `4096x4096`（16777216）] * 宽高比取值范围：[1/16, 16]

说明

有效示例 ：3750x1250。总像素值 3750x1250=4687500，符合 [3686400, 16777216] 的区间要求；宽高比 3750/1250=3，符合 [1/16, 16] 的区间要求，故该示例值有效。

采用方式 1 时，模型实际映射的宽高像素参考值： |分辨率 |宽高比 |宽高像素值 | |---|---|---| |2K |1:1 |2048x2048 | | |4:3 |2304x1728 | | |3:4 |1728x2304 | | |16:9 |2848x1600 | | |9:16 |1600x2848 | | |3:2 |2496x1664 | | |2:3 |1664x2496 | | |21:9 |3136x1344 | |4K |1:1 |4096x4096 | | |4:3 |4704x3520 | | |3:4 |3520x4704 | | |16:9 |5504x3040 | | |9:16 |3040x5504 | | |3:2 |4992x3328 | | |2:3 |3328x4992 | | |21:9 |6240x2656 | **Seedream 4.0** 支持以下两种方式，不可混用： * 方式 1：指定分辨率，并在 prompt 中用自然语言描述图片宽高比、图片形状或图片用途，最终由模型判断生成图片的大小。 * 可选值：`1K`、`2K`、`4K` * 方式 2：指定生成图像的宽高像素值。 * 默认值：`2048x2048` * 总像素取值范围：[`1280x720`（921600）, `4096x4096`（16777216）] * 宽高比取值范围：[1/16, 16]

说明

有效示例 ：1600x600。总像素值 1600x600=960000，符合 [921600, 16777216] 的区间要求；宽高比 1600/600=8/3，符合 [1/16, 16] 的区间要求，故该示例值有效。

无效示例 ：800x800。总像素值 800x800=640000，未达到 921600 的最低要求；宽高 800/800=1，虽符合 [1/16, 16] 的区间要求，但未同时满足两项限制，故该示例值无效。

采用方式 1 时，模型实际映射的宽高像素参考值： |分辨率 |宽高比 |宽高像素值 | |---|---|---| |1K |1:1 |1024x1024 | | |4:3 |1152x864 | | |3:4 |864x1152 | | |16:9 |1280x720 | | |9:16 |720x1280 | | |3:2 |1248x832 | | |2:3 |832x1248 | | |21:9 |1512x648 | |2K |1:1 |2048x2048 | | |4:3 |2304x1728 | | |3:4 |1728x2304 | | |16:9 |2848x1600 | | |9:16 |1600x2848 | | |3:2 |2496x1664 | | |2:3 |1664x2496 | | |21:9 |3136x1344 | |4K |1:1 |4096x4096 | | |4:3 |4704x3520 | | |3:4 |3520x4704 | | |16:9 |5504x3040 | | |9:16 |3040x5504 | | |3:2 |4992x3328 | | |2:3 |3328x4992 | | |21:9 |6240x2656 | **optimize_prompt_options** `object` | 提示词优化配置提示词优化功能的配置。 **mode** `string` `默认值 standard` | 优化模式 `optimize_prompt_options.mode` 设置提示词优化功能使用的模式。 * `standard`：标准模式，生成内容的质量更高，耗时较长。 * `fast`：快速模式，生成内容的耗时更短，效果略低于标准模式；Seedream 5.0 lite / 4.5 当前不支持。

说明

如您的业务对生成时延较为敏感，推荐使用 fast 模式以节省等待时间。

**output_format** `string` `默认值 jpeg` | 图像格式指定生成图像的文件格式。可选值：`png`、`jpeg`。 **模型支持** ： * `Seedream 5.0 pro` * `Seedream 5.0 lite` **response_format** `string` `默认值 url` | 返回格式指定生成图像的返回格式。支持以下两种返回方式： * `url`：返回图片下载链接， **链接在图片生成后 24 小时内有效，请及时下载图片** 。 * `b64_json`：以 Base64 编码字符串的 JSON 格式返回图像数据。 **sequential_image_generation** `string` `默认值 disabled` | 组图模式控制是否关闭组图功能（组图：基于您输入的内容，生成的一组内容关联的图片）。 * `auto`：自动判断模式，模型会根据用户提供的提示词自主判断是否返回组图以及组图包含的图片数量。 * `disabled`：关闭组图功能，模型只会生成一张图。组图输出示例详见 [Seedream 图像创作教程 - 组图输出](https://docs.volcengine.com/docs/82379/1824121#ec79cfda)。 **模型支持** ： * `Seedream 5.0 lite` * `Seedream 4.5` * `Seedream 4.0` **sequential_image_generation_options** `object` | 组图配置组图功能的配置。仅当 `sequential_image_generation` 为 `auto` 时生效。 **模型支持** ： * `Seedream 5.0 lite` * `Seedream 4.5` * `Seedream 4.0` **max_images** `integer` `默认值 15` | 最大生成数量 `sequential_image_generation_options.max_images` 指定本次请求，最多可生成的图片数量。

说明

实际可生成的图片数量，除受到 max_images 影响外，还受到输入的参考图数量影响。 输入的参考图数量+最终生成的图片数量≤15 张 。

**取值范围** ：`[1, 15]` **stream** `boolean` `默认值 false` | 流式输出开关控制是否开启流式输出模式。 * `false`：非流式输出模式，等待所有图片全部生成结束后再一次性返回所有信息。 * `true`：流式输出模式，即时返回每张图片输出的结果。在生成单图和组图的场景下，流式输出模式均生效。流式输出示例详见 [Seedream 图像创作教程 - 流式输出](https://docs.volcengine.com/docs/82379/1824121#e5bef0d7)。 **模型支持** ： * `Seedream 5.0 lite` * `Seedream 4.5` * `Seedream 4.0` **tools** `object[]` | 工具配置配置模型要调用的工具。 **模型支持** ： * `Seedream 5.0 lite` **type** `string` `必选` | 工具类型 `tools.type` 指定使用的工具类型。 * `web_search`：联网搜索功能。

说明

开启联网搜索后，模型会根据用户的提示词自主判断是否搜索互联网内容（如商品、天气等），提升生成图片的时效性，但也会增加一定的时延。

实际搜索次数可通过字段 usage.tool_usage.web_search 查询，如果为 0 表示未搜索。

**watermark** `boolean` `默认值 true` | 水印开关是否在生成的图片中添加水印。 * `false`：不添加水印。 * `true`：在图片右下角添加“AI 生成”字样的水印标识。 ## 响应参数 ### 非流式调用响应 **created** `integer` | 创建时间本次请求创建时间的 Unix 时间戳（秒） **model** `string` | 模型 ID 本次请求使用的模型 ID（模型名称\-版本） **data** `object[]` | 图像数据输出图像的信息。组图场景下，每个数组元素对应一张图片或一次错误

说明

Seedream 5.0 lite / 4.5 / 4.0 模型生成组图场景下，组图生成过程中某张图生成失败时：

若失败原因为审核不通过：仍会继续请求下一个图片生成任务，即不影响同请求内其他图片的生成流程。

若失败原因为内部服务异常（500）：不会继续请求下一个图片生成任务。

**b64_json** `string` | 图片 Base64 数据 `data.b64_json` 图片的 Base64 信息，当 `response_format` 指定为 `b64_json` 时返回 **error** `object` | 单图错误信息 `data.error` 某张图片生成失败时返回的错误信息。其他成功生成的图片不受影响 **code** `string` | 错误码 `data.error.code` 错误码，请参见 [错误码](https://docs.volcengine.com/docs/82379/1299023) **message** `string` | 错误消息 `data.error.message` 错误提示信息，便于排查问题 **output_format** `string` | 输出格式 `data.output_format` 输出图像的格式信息（`png` 或 `jpeg`）。 **模型支持** ： * `Seedream 5.0 pro` **size** `string` | 图像尺寸 `data.size` 图像的宽高像素值，格式 `<宽像素>x<高像素>`，例如 `2048x2048`。 **url** `string` | 图片 URL `data.url` 图片 URL，当 `response_format` 指定为 `url` 时返回。该链接将在生成后 **24 小时内失效** ，请务必及时保存图像。推荐配置火山引擎 TOS 提供的数据订阅功能，将您的模型推理产物自动转存到自己的 TOS 桶中，便于长期备份或二次加工。详细介绍请参见 [TOS 数据订阅](https://docs.volcengine.com/docs/6349/1366744)。 **error** `object` | 错误信息本次请求顶层错误信息。当整个请求未能生成任何图片时返回 **code** `string` | 错误码 `error.code` 错误码，请参见 [错误码](https://docs.volcengine.com/docs/82379/1299023) **message** `string` | 错误消息 `error.message` 错误提示信息，便于排查问题 **tools** `object[]` | 工具调用列表本次请求中配置并被模型调用的工具列表 **模型支持** ： * `Seedream 5.0 lite` **type** `string` | 工具类型 `tools.type` 指定使用的工具类型。 * `web_search`：联网搜索功能。

说明

开启联网搜索后，模型会根据用户的提示词自主判断是否搜索互联网内容（如商品、天气等），提升生成图片的时效性，但也会增加一定的时延。

实际搜索次数可通过字段 usage.tool_usage.web_search 查询，如果为 0 表示未搜索。

**usage** `object` | 用量信息本次请求的用量信息，包括生成图片数量、消耗的 token 数量等 **generated_images** `integer` | 成功生成图片数 `usage.generated_images` 模型成功生成的图片张数，不包含生成失败的图片。仅对成功生成图片按张数进行计费 **input_images** `integer` | 输入图片数 `usage.input_images` 输入模型的图片张数。 **模型支持** ： * `Seedream 5.0 pro` **output_tokens** `integer` | 输出 token 数 `usage.output_tokens` 模型生成的图片花费的 token 数量。计算逻辑为：`sum(图片长 * 图片宽) / 256` 后取整 **tool_usage** `object` | 工具用量 `usage.tool_usage` 使用工具的用量信息 **模型支持** ： * `Seedream 5.0 lite` **web_search** `integer` | 联网搜索次数 `usage.tool_usage.web_search` 调用联网搜索工具的次数，仅开启联网搜索时返回。如果为 0 表示未搜索 **total_tokens** `integer` | 总 token 数 `usage.total_tokens` 本次请求消耗的总 token 数量。当前不计算输入 token，故与 `output_tokens` 值一致 ### 流式调用响应字段结构详见 [图片生成流式响应事件](https://docs.volcengine.com/docs/82379/1824137)。

火山方舟