OpenAPI 参考

Modelink API · 图像

Modelink 图像 API，提供 OpenAI 格式、火山格式的同步生图，以及基于 Fal 格式的异步任务能力。Fal 格式接口使用 Authorization: Key {api_key}；其他接口使用 Bearer 鉴权。

版本 1.0.0

火山格式图片生成

POST

/volcengine/v3/images/generations

使用火山格式图片生成协议同步调用平台支持的图片模型。文生图、图生图、多图融合和图层拆分共用一个接口：POST /volcengine/v3/images/generations。

当前支持模型：

bytedance/doubao-seedream-5.0-pro
bytedance/doubao-seedream-5.0-flash
byteplus/dola-seedream-5.0-pro
byteplus/dola-seedream-5.0-flash

四个模型均通过 model 字段选择，并使用下方 Schema 中声明的 Seedream 5.0 Pro/Flash 参数。普通生图支持 0～10 张参考图；图层拆分必须且只能输入 1 张 PNG 或 JPEG，并允许 prompt 为空。未在 Schema 中声明的 SDK 通用字段不属于当前四个模型的公开能力。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

请求体

请求体属性

modelenum, 必填
模型 ID，必须是当前平台已接入的火山格式图片生成模型。
- bytedance/doubao-seedream-5.0-pro
- bytedance/doubao-seedream-5.0-flash
- byteplus/dola-seedream-5.0-pro
- byteplus/dola-seedream-5.0-flash
promptstring
普通生图必填，去除首尾空白后不能为空；图层拆分可以省略或传空字符串，也可以指定需要拆分的目标元素。建议中文不超过 300 字、英文不超过 600 词。
imagestring | string[]
参考图，支持可访问的公网 URL 或 data:image/<格式>;base64,<数据>。普通生图最多 10 张；支持 jpeg、png、webp、bmp、tiff、gif、heic、heif，单图不超过 30 MB，宽高比为 1/16～16，宽和高均大于 14 px，总像素为 196～36000000。图层拆分必须且只能传 1 张 PNG 或 JPEG，单图不超过 30 MB，总像素为 262144～36000000。
- oneOf[0]string
  可选。
- oneOf[1]string[]
  可选。
response_formatenum
图片返回格式。url 返回约 24 小时有效的临时链接；b64_json 返回 Base64 数据。响应会在 data[].url 和 data[].b64_json 中二选一。
default: url
- url
- b64_json
sizestring
输出尺寸。普通生图支持 1K、1.5K、2K 或 widthxheight，默认 2K；自定义尺寸总像素须为 921600～4624220，宽高比须为 1/16～16。图层拆分仅支持 1K、1.5K、2K、auto，默认 auto。
watermarkboolean
是否添加 AI 生成水印。
default: true
optimize_prompt_optionsobject
提示词优化配置。Seedream 5.0 Pro 支持 standard 和 fast；Seedream 5.0 Flash 仅支持 standard。
additionalProperties: false
- modeenum
  standard 质量更高、耗时较长；fast 延迟更低，但仅 Seedream 5.0 Pro 支持。
  default: standard
  - standard
  - fast
output_formatenum
输出格式，支持 jpeg 或 png。通常默认 jpeg；background=transparent 且省略该字段时默认 png，显式传入 jpeg 会报错。图层拆分时仅控制底图，拆分图层始终为 PNG。
- jpeg
- png
backgroundenum
背景透明度。transparent 仅适用于图生图，且只能输入 1 张带透明通道的图片；显式指定 output_format 时只能使用 png。输入 JPEG 等不支持透明通道的格式会报错。
default: opaque
- opaque
- transparent
layer_decompositionboolean
是否开启图层拆分。true 时将单张输入图拆为 1 张底图和最多 16 个独立图层；任一图层生成失败时整次请求失败。必须传 JSON 布尔值，不能传字符串 "true"。
default: false
allOf[0]
可选。

请求

POST/volcengine/v3/images/generations

curl https://api.qnaigc.com/volcengine/v3/images/generations \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "bytedance/doubao-seedream-5.0-pro",
  "prompt": "一只红色陶瓷茶壶放在浅色木桌上，摄影棚柔光，4:3 构图",
  "size": "1.5K",
  "watermark": false,
  "response_format": "url"
}'

响应

object

图片生成成功。

响应体属性

modelstring, 必填
实际执行的模型标识。
createdinteger, 必填
创建时间，Unix 时间戳（秒）。
data[], 必填
- urlstring<uri>
  临时图片 URL。response_format=url 时返回，通常约 24 小时有效。
- b64_jsonstring
  Base64 图片数据。response_format=b64_json 时返回。
- sizestring, 必填
  实际输出尺寸，格式为 widthxheight。
- output_formatenum, 必填
  实际输出格式。
  - jpeg
  - png
- z_indexinteger
  图层顺序。底图为 0，其他图层从 1 开始。
- namestring
  图层名称。
- descriptionstring
  图层内容描述。
- bounding_boxobject
  additionalProperties: false
  - absoluteinteger[]
    [left, top, right, bottom] 绝对像素坐标。
  - normalizedinteger[]
    0～1000 范围的归一化坐标。
- anyOf[0]
  可选。
- anyOf[1]
  可选。
usageobject
additionalProperties: false
- input_imagesinteger
  输入图片数量。
  minimum: 0
- generated_imagesinteger
  生成图片数量；图层拆分时包含底图和图层。
  minimum: 0
- output_tokensinteger
  上游返回的技术用量。
  minimum: 0
- total_tokensinteger
  上游返回的总技术用量。
  minimum: 0

响应

{
  "model": "doubao-seedream-5-0-pro-260628",
  "created": 1790234881,
  "data": [
    {
      "url": "https://example.com/generated.jpeg",
      "size": "1792x1344",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "input_images": 0,
    "generated_images": 1,
    "output_tokens": 9408,
    "total_tokens": 9408
  }
}