天枢AI-TokenHub

简体中文

English

简体中文

English

Appearance

Request
Response

图片生成API ​

POST https://ark.cn-beijing.volces.com/api/v3/images/generations

本文介绍图片生成模型如 Seedream系列的调用 API ，包括输入输出参数，取值范围，注意事项等信息，供您使用接口时查阅字段含义。

图片生成能力介绍 ​

不同模型支持的图片生成能力简介：

  • seedream 5.0 pro（new）
    • 图层拆分：支持将单张图片拆解为底图（1 张）+ 多个图层输出（最多 16 个图层）。
    • 交互编辑：支持通过坐标、框选、箭头等多种方式指定编辑位置，精准编辑图片。
    • 生成单图（不支持配置 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）+ 文本提示词 生成单张图片。
      • 单图生图，根据您输入的 单张参考图片+文本提示词 生成单张图片。
      • 文生图，根据您输入的 文本提示词 生成单张图片。

请求参数 ​

请求体 ​

model string (必选) ​

您需要调用的模型的 ID（Model ID）。

您也可通过 Endpoint ID 来调用模型，获得限流、计费类型（前付费/后付费）、运行状态查询、监控、安全等高级能力。

prompt string (必选) ​

用于生成图像的提示词，支持中英文。（查看提示词指南：Seedream 4.0-5.0 提示词指南）

提示词语言支持：所有模型均支持中英文提示词；Seedream 5.0 pro 额外支持俄语、阿拉伯语、菲律宾语、泰语、土耳其语、韩语、马来语、西班牙语、葡萄牙语、印尼语、法语、德语、越南语、日语。

建议不超过 300 个汉字或 600 个英文单词。字数过多信息容易分散，模型可能因此忽略细节，只关注重点，造成图片缺失部分元素。

图层拆分场景（可选）：当开启图层拆分模式（layer_decomposition 为 true）时，prompt 可选，用于指定图层拆分意图，模型根据提示词意图识别并拆分指定元素；若不传入提示词，模型将自动识别图片中的所有主要元素并拆分为独立图层。

image string/array ​

输入的图片信息，支持 URL 或 Base64 编码。其中，seedream-5.0-lite/4.5/4.0 支持单图或多图输入（查看多图融合示例）。

  • 图片 URL：请确保图片 URL 可被访问。
  • Base64 编码：请遵循此格式 data:image/<format>;base64,<base64_data>。注意 <format> 需小写，如：
    • data:image/png;base64,<base64_image>

图片生成场景（可选）

  • 图片格式：jpeg, png（seedream-5.0-lite/4.5/4.0 模型新增支持 webp, bmp, tiff, gif, heic, heif 格式）
  • 宽高比（宽/高）范围：
    • [1/16, 16]（适用模型：seedream-5.0-lite/4.5/4.0）
  • 宽高长度（px）：> 14
  • 大小：不超过 30MB
  • 总像素：不超过 6000×6000=36000000 px（对单张图宽度和高度的像素乘积限制，而不是对宽度或高度的单独值进行限制）
  • 参考图数量：seedream-5.0-pro 最多支持传入 10 张参考图；seedream-5.0-lite/4.5/4.0 最多支持传入 14 张参考图。

图层拆分场景（必选，仅 Seedream 5.0 pro）

当开启图层拆分模式时（layer_decomposition 为 true），image 为必选参数，且仅支持输入单张图片（传入多张报错）。

  • 图片格式：png、jpeg
  • 宽高比：[1/16, 16]
  • 大小：不超过 30MB
  • 总像素（宽×高）范围：[512×512（262144）, 6000×6000（3600万）]（对单张图宽度和高度的像素乘积限制，而不是对宽度或高度的单独值进行限制）

layer_decomposition boolean 默认值 false（new，仅 Seedream 5.0 pro） ​

控制是否开启图层拆分功能。图层拆分会将单张图片的主体、背景、文字等内容自动拆解为 1 张底图和最多 16 个可独立编辑的图层。每个图层为带透明通道的 PNG 图片。

  • true：图层拆分模式。模型将输入图拆解为一张底图和多个图层。
  • false：图片生成模式，不进行图层拆分。

说明

  • 仅支持输入单张待拆分图，传入多张报错。
  • 任一图层生成失败，整体请求报错，不支持部分成功。
  • 若提示词要求的拆分数量超过上限，可能导致部分图层信息丢失。
  • 响应结构体 data 中，将返回每个产出图层的位置和内容信息，包括图层顺序（z_index）、边界框信息（bounding_box）、名称（name）和描述（description）。

size string ​

  • 方式 1（推荐）| 指定分辨率档位，并在 prompt 中用自然语言描述图片宽高比、图片形状或图片用途，最终由模型判断生成图片的大小。
    • 默认值：2K
    • 可选值：1K、1.5K、2K
  • 方式 2 | 指定生成图像的宽高像素值：
    • 总像素取值范围：[1280x720=921600, 2048x2048x1.1025=4624220]
    • 宽高比取值范围：[1/16, 16]

说明

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

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

  • 有效示例：2048x1024
    总像素值 2048×1024=2097152，符合 [921600, 4624220] 的区间要求；宽高比 2048/1024=2，符合 [1/16, 16] 的区间要求，故该示例值有效。
  • 无效示例：512x512
    总像素值 512×512=262144，未达到 921600 的最低要求，故该示例值无效。

推荐的宽高像素值

分辨率宽高比宽高像素值
1K1:11024x1024
4:31152x864
3:4864x1152
16:91424x800
9:16800x1424
3:21248x832
2:3832x1248
21:91568x672
1.5K1:11536x1536
4:31792x1344
3:41344x1792
16:92048x1152
9:161152x2048
3:21872x1248
2:31248x1872
21:92352x1008
2K1:12048x2048
4:32368x1776
3:41776x2368
16:92816x1584
9:161584x2816
3:22496x1664
2:31664x2496
21:93136x1344

图层拆分场景（仅 Seedream 5.0 pro）：仅支持通过指定分辨率档位的方式设置。size 默认值 auto，可选值 1K、1.5K、2K、auto（根据输入图的尺寸和宽高比进行输出）。输出规则：底图分辨率与 size 指定的分辨率一致，且与原待拆分图宽高比一致；各图层分辨率与 size 指定的分辨率接近，且各自保持其在原图中的宽高比。价格说明：1.5K 与 1K 价格相同。

sequential_image_generation string 默认值 disabled（仅 seedream-5.0-lite/4.5/4.0 支持，Seedream 5.0 pro 不支持） ​

控制是否开启组图功能。

说明 组图：基于您输入的内容，生成的一组内容关联的图片。

  • auto：自动判断模式，模型会根据用户提供的提示词自主判断是否返回组图以及组图包含的图片数量。
  • disabled：关闭组图功能，模型只会生成一张图。

sequential_image_generation_options object ​

组图功能的配置，仅当 sequential_image_generation 为 auto 时生效。

属性

sequential_image_generation_options.max_images integer 默认值 15 ​

指定本次请求最多可生成的图片数量。

  • 取值范围：[1, 15]

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

tools array of object ​

仅 seedream-5.0-lite 支持该参数（Seedream 5.0 pro / 4.5 / 4.0 不支持）。 配置模型要调用的工具。

属性

  • tools.type string 指定使用的工具类型。
    • web_search：联网搜索功能。

说明

  • 开启联网搜索后，模型会根据用户的提示词自主判断是否搜索互联网内容（如商品、天气等），以提升生成图片的时效性，但也会增加一定的时延。
  • 实际搜索次数可通过字段 usage.tool_usage.web_search 查询，如果为 0 表示未搜索。

stream Boolean 默认值 false（仅 seedream-5.0-lite/4.5/4.0 支持，Seedream 5.0 pro 不支持） ​

控制是否开启流式输出模式。

  • false：非流式输出模式，等待所有图片全部生成结束后再一次性返回所有信息。
  • true：流式输出模式，即时返回每张图片输出的结果。在生成单图和组图的场景下，流式输出模式均生效。

output_format string 默认值 jpeg（仅 Seedream 5.0 pro / 5.0 lite 支持） ​

指定生成图像的文件格式。可选值：

  • png
  • jpeg

说明

  • seedream-4.5/4.0 模型生成图像的文件格式默认为 jpeg，不支持自定义设置。
  • 图层拆分场景下，output_format 仅控制底图的输出格式，图层始终以 png 格式输出。

background string 默认值 opaque（new，仅 Seedream 5.0 pro） ​

用于控制是否生成带透明通道的图片。可选值：

  • transparent：透明背景模式，输出带有透明背景的图。
  • opaque：不透明背景模式，生成常规的实体背景图。

使用限制

  • 仅支持图生图场景，且只支持输入 1 张带透明通道 的图片。
  • 透明背景模式下，输出图片默认为 png 格式，若同时配置 output_format 为 jpeg，将触发报错。
  • 若传入了不支持透明通道的文件格式（如 jpeg），将触发报错。

response_format string 默认值 url ​

指定生成图像的返回格式。支持以下两种返回方式：

  • url：返回图片下载链接；链接在图片生成后 24 小时内有效，请及时下载图片。
  • b64_json：以 Base64 编码字符串的 JSON 格式返回图像数据。

watermark Boolean 默认值 true ​

是否在生成的图片中添加水印。

  • false：不添加水印。
  • true：在图片右下角添加"AI 生成"字样的水印标识。

optimize_prompt_options object ​

提示词优化功能的配置。

属性

  • optimize_prompt_options.mode string 默认值 standard 设置提示词优化功能使用的模式。
    • standard：标准模式，生成内容的质量更高，耗时较长。
    • fast：快速模式，生成内容的耗时更短，质量一般；seedream-5.0-lite/4.5 当前不支持（Seedream 5.0 pro / 4.0 支持）。

响应参数 ​

流式响应参数 ​

请参见流式响应文档

非流式响应参数 ​

model string ​

本次请求使用的模型 ID（模型名称-版本）。

created integer ​

本次请求创建时间的 Unix 时间戳（秒）。

data array ​

输出图像的信息。不同任务场景返回字段有所区别，其中 url、b64_json、size、output_format 为公共返回字段。

说明

  • 组图生成场景（仅 seedream-5.0-lite/4.5/4.0），若某张图生成失败，额外返回该图片的错误信息（error）。
    • 若失败原因为审核不通过：仍会继续请求下一个图片生成任务，即不影响同请求内其他图片的生成流程。
    • 若失败原因为内部服务异常（500）：不会继续请求下一个图片生成任务。
  • 图层拆分场景（仅 Seedream 5.0 pro），额外返回每个图层的叠放顺序（z_index）、名称（name）、描述（description）、边界框坐标（bounding_box）。

图片信息 object 生成成功的图片信息。

属性

  • data.url string 图片的 url 信息，当 response_format 指定为 url 时返回。该链接将在生成后 24 小时内失效，请务必及时保存图像。
  • data.b64_json string 图片的 base64 信息，当 response_format 指定为 b64_json 时返回。
  • data.size string 图像的宽高像素值，格式 <width>x<height>，如 2048x2048。
  • data.output_format string（new，仅 Seedream 5.0 pro / 5.0 lite） 输出图像的格式信息（png 或 jpeg）。图层拆分场景下，output_format 仅控制底图的输出格式，图层始终为 png。

图层拆分场景字段（仅 Seedream 5.0 pro 返回）

  • data.z_index integer（new）：图层的叠放顺序索引。底图固定为 0，图层从 1 开始递增，数值越大越靠上层。
  • data.name string（new）：当前图层拆分元素的名称/标签。由模型根据拆分出的主体特征自动生成，用于标识该图层的主体内容。
  • data.description string（new）：当前图层拆分元素的详细描述。由模型生成的语义描述，提供比 name 更丰富的图层特征（如颜色、状态、材质等）。
  • data.bounding_box object（new）：输出图层在输出底图坐标系中所占区域的边界框信息。仅图层返回该字段；底图覆盖整张画布，不返回该字段。
    • data.bounding_box.absolute array：输出图层边界框在输出底图坐标系中的绝对像素坐标，格式为 [left, top, right, bottom]，输出底图左上角坐标为 (0, 0)。left/top 为图层左/上边界到输出底图左/上边界的距离，right/bottom 为图层右/下边界到输出底图左/上边界的距离。
    • data.bounding_box.normalized array：归一化坐标，由绝对坐标按输出底图宽高换算至 [0, 1000] 的离散整数区间，格式为 [left, top, right, bottom]。0 表示底图最左/上方，1000 表示底图最右/下方。

错误信息 object 某张图片生成失败，错误信息。

属性

  • data.error object 错误信息结构体。
    • data.error.code 某张图片生成错误的错误码，请参见错误码。
    • data.error.message 某张图片生成错误的提示信息。

tools array of object ​

本次请求，配置的模型调用工具

属性

  • tools.type string 配置的调用工具类型。
    • web_search：联网搜索工具。

usage object ​

本次请求的用量信息。

属性

  • usage.generated_images integer 模型成功生成的图片张数，不包含生成失败的图片。 仅对成功生成图片按张数进行计费。
  • usage.input_images integer（new，仅 Seedream 5.0 pro 返回） 输入模型的图片张数。
  • usage.output_tokens integer 模型生成的图片花费的 token 数量。 计算逻辑为：计算 sum(图片长×图片宽)/256，然后取整。
  • usage.total_tokens integer 本次请求消耗的总 token 数量。 当前不计算输入 token，故与 output_tokens 值一致。
  • usage.tool_usage object 使用工具的用量信息。
    • usage.tool_usage.web_search integer 调用联网搜索工具次数，仅开启联网搜索时返回。

error object ​

本次请求，如发生错误，对应的错误信息。

属性

  • error.code string 请参见错误码。
  • error.message string 错误提示信息