生成图片

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

图片链接 24 小时后失效

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

调用流程

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

授权

BearerAuth

Authorization<token>

需要鉴权的接口请传入 Bearer <token> 形式的访问令牌。

位置: header

请求主体

application/json

图片生成请求

TypeScript 定义

在 TypeScript 中使用 request body 类型。

图片生成请求体，参数集对齐火山方舟 Ark images/generations。 model 填平台公开模型 ID，转发上游前会被替换为部署的上游模型 ID——这是平台唯一改写的字段；本接口没有身份标识字段（火山图片接口未定义 safety_identifier / user），平台不注入。平台只校验它自己要消费的字段（model / prompt / image 张数 / size / stream / layer_decomposition / 组图张数上限），其余字段与取值一律原样转发给上游，包括本表没有列出的字段，合不合法由上游回答。stream=true 是否可用由所选模型对应部署的能力决定，不支持的型号返回 400 image_invalid_field（param=stream）。

background?string

图片透明通道，默认 opaque（常规实体背景）。transparent 输出透明背景图，仅支持输入 1 张带透明通道图片的图生图场景，且与 output_format=jpeg 互斥。

值于

"opaque"
"transparent"

image?string

参考图片，单个字符串或字符串数组，上限张数随所选模型对应部署的能力而定（超出返回 400 image_invalid_field，param=image）。每项支持公网可访问的图片 URL，或 data:image/<格式>;base64,<编码> 形式的 Base64（<格式> 需小写）；平台只数张数、不校验每项内容，其他形状原样送上游由上游报错。数不出张数（既不是字符串也不是数组）返回 400——张数是计费输入。图层拆分场景必须恰好传 1 张。超大参考图请改用 URL 传入，避免请求体超出上限。

layer_decomposition?boolean

图层拆分开关，默认 false。true 时模型把输入图拆解为 1 张底图 + 最多 16 个带透明通道的 PNG 图层，data[] 项额外返回 z_index / name / description / bounding_box。仅 Seedream 5.0 pro 支持；开启时必须且只能传 1 张 image，任一图层生成失败整体请求报错。

model*string

要调用的平台公开模型 ID（模型目录中 runtimeType=image 的已启用模型）。转发上游前会被替换为部署配置的上游模型 ID，响应中的 model 会改回本值。

optimize_prompt_options?

提示词优化配置。

output_format?string

生成图像的文件格式，默认 jpeg，可选 png。图层拆分场景下仅控制底图格式，图层始终输出 PNG。

值于

"jpeg"
"png"

prompt?string

提示词。图片生成场景必填，用于描述生成图像的内容；图层拆分场景可选，用于指定拆分意图，不传时模型自动识别图片中的主要元素并拆分为独立图层。所有模型支持中英文；建议中文不超过 300 字、英文不超过 600 词。提示词会先经过平台文本内容安全检测，命中时返回 400 InputTextSensitiveContentDetected。

response_format?string

返回格式，默认 url（图片下载链接，生成后 24 小时内有效，请及时保存）； b64_json 以 Base64 编码字符串返回图像数据。

值于

"url"
"b64_json"

sequential_image_generation?string

组图模式，默认 disabled（只生成一张图）。auto 时模型根据提示词自主判断是否返回组图及其张数。输入参考图数量 + 最终生成图片数量 ≤ 15 张。平台只认 auto / disabled 用于定档，其他取值不拒绝、原样送上游，但冻结额会按该部署能产出的最大张数保守取（上游拒绝后全额释放）。

值于

"auto"
"disabled"

sequential_image_generation_options?

组图配置，仅当 sequential_image_generation=auto 时生效。

size?string

生成图像的尺寸。支持两种写法，不可混用：显式宽高 <宽>x<高>（如 2048x2048，宽高均须在 [1, 16384] 内，x 亦接受 X、×、*），或档位词（如 1K、2K、4K，可选值随模型不同，以火山方舟文档为准，平台原样透传）。

stream?boolean

流式输出开关，默认 false。传 true 时响应改为 text/event-stream：上游 SSE 事件帧原样转发（仅帧内顶层 model 改回公开模型 ID），HTTP 状态恒 200 （单张失败与整请求失败都在事件里表达）。 是否可用由该模型对应部署的能力决定：Seedream 5.0 pro 不支持流式， lite / 4.5 / 4.0 支持；打到不支持的型号返回 400 InvalidParameter （reasonCode=image_invalid_field，param=stream）——字段本身受支持，只是这条线路服务不了 true，所以处置是换模型而不是删字段。

tools?array<>

工具配置。上游当前文档只定义了 [{"type":"web_search"}]（联网搜索）；平台不校验该字段，原样透传，其他取值由上游报错。联网搜索次数可从响应 usage.tool_usage.web_search 查询，不计费。

watermark?boolean

水印开关，默认 true（在图片右下角添加"AI 生成"水印标识）；false 不添加。

响应主体

`application/json`

在线请求

「发送」会向所选服务器地址发起真实调用，与生产环境请求等效，可能产生计费。

请求示例

curl -X POST "https://example.com/api/v3/images/generations" \  -H "Content-Type: application/json" \  -d '{    "model": "doubao-seedream-4-0",    "prompt": "一只在草地上奔跑的柯基犬，阳光明媚，浅景深",    "size": "2K",    "response_format": "url",    "watermark": true  }'

响应示例

{  "created": 1756000000,  "data": [    {      "b64_json": "iVBORw0KGgoAAAANSUhEUg...",      "bounding_box": {        "absolute": [          0        ],        "normalized": [          0        ]      },      "description": "一只浅棕色短腿柯基犬，正在奔跑",      "error": {        "code": "OutputImageSensitiveContentDetected",        "message": "The generated image failed the content safety check."      },      "name": "柯基犬",      "output_format": "png",      "size": "2048x2048",      "url": "https://ark-generated.example.com/2026/08/24/img-1.png",      "z_index": 1    }  ],  "error": {    "code": "OutputImageSensitiveContentDetected",    "message": "The generated image failed the content safety check."  },  "model": "doubao-seedream-4-0",  "tools": [    {      "type": "web_search"    }  ],  "usage": {    "generated_images": 1,    "input_images": 0,    "output_tokens": 16384,    "tool_usage": {      "web_search": 1    },    "total_tokens": 16384  }}

{  "error": {    "code": "InvalidParameter",    "message": "The parameter content specified in the request is not valid. Request id: 0217790892668142434549f79b621a35",    "param": "content",    "reasonCode": "seedance_text_blocked_by_moderation",    "requestId": "seedance_req_019e8808-d40e-7ccd-873c-072b78b15437",    "type": "BadRequest"  }}

{  "error": {    "code": "InvalidParameter",    "message": "The parameter content specified in the request is not valid. Request id: 0217790892668142434549f79b621a35",    "param": "content",    "reasonCode": "seedance_text_blocked_by_moderation",    "requestId": "seedance_req_019e8808-d40e-7ccd-873c-072b78b15437",    "type": "BadRequest"  }}

{  "error": {    "code": "InvalidParameter",    "message": "The parameter content specified in the request is not valid. Request id: 0217790892668142434549f79b621a35",    "param": "content",    "reasonCode": "seedance_text_blocked_by_moderation",    "requestId": "seedance_req_019e8808-d40e-7ccd-873c-072b78b15437",    "type": "BadRequest"  }}

{  "error": {    "code": "InvalidParameter",    "message": "The parameter content specified in the request is not valid. Request id: 0217790892668142434549f79b621a35",    "param": "content",    "reasonCode": "seedance_text_blocked_by_moderation",    "requestId": "seedance_req_019e8808-d40e-7ccd-873c-072b78b15437",    "type": "BadRequest"  }}

{  "error": {    "code": "InvalidParameter",    "message": "The parameter content specified in the request is not valid. Request id: 0217790892668142434549f79b621a35",    "param": "content",    "reasonCode": "seedance_text_blocked_by_moderation",    "requestId": "seedance_req_019e8808-d40e-7ccd-873c-072b78b15437",    "type": "BadRequest"  }}

{  "error": {    "code": "InvalidParameter",    "message": "The parameter content specified in the request is not valid. Request id: 0217790892668142434549f79b621a35",    "param": "content",    "reasonCode": "seedance_text_blocked_by_moderation",    "requestId": "seedance_req_019e8808-d40e-7ccd-873c-072b78b15437",    "type": "BadRequest"  }}

{  "error": {    "code": "InvalidParameter",    "message": "The parameter content specified in the request is not valid. Request id: 0217790892668142434549f79b621a35",    "param": "content",    "reasonCode": "seedance_text_blocked_by_moderation",    "requestId": "seedance_req_019e8808-d40e-7ccd-873c-072b78b15437",    "type": "BadRequest"  }}

尺寸（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。

尺寸校验范围

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

流式输出

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），该请求不计费。

事件名与分帧结构与火山方舟一致，字段结构见图片生成流式响应事件，形如：

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}}

解析时遵循以下约定：

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

常见问题

组图中部分图片生成失败

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

{
  "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，不计费：

{
  "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"
  }
}

调整提示词后重新提交。

火山方舟图片生成总览：接入信息、模型能力、计费口径与错误码
Seedream 图像创作教程（火山方舟）
Seedream 4.0-5.0 提示词指南（火山方舟）

生成图片

调用流程

接口详情

授权

请求主体

响应主体

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

在线请求

请求示例

响应示例

尺寸（size）

流式输出

常见问题

组图中部分图片生成失败

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

请求体超出上限（413）

请求了模型不支持的能力

参考文档

本页目录

生成图片

200application/json

400application/json

401application/json

403application/json

404application/json

413application/json

429application/json

500application/json

本页目录

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`