Seedream

curl --request POST \
  --url https://api.ppio.com/v3/bytedance-cn/api/v3/images/generations

const options = {method: 'POST'};

fetch('https://api.ppio.com/v3/bytedance-cn/api/v3/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ppio.com/v3/bytedance-cn/api/v3/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ppio.com/v3/bytedance-cn/api/v3/images/generations"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.ppio.com/v3/bytedance-cn/api/v3/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

bytedance-cn

api

images

generations

Seedream

curl --request POST \
  --url https://api.ppio.com/v3/bytedance-cn/api/v3/images/generations

const options = {method: 'POST'};

fetch('https://api.ppio.com/v3/bytedance-cn/api/v3/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ppio.com/v3/bytedance-cn/api/v3/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ppio.com/v3/bytedance-cn/api/v3/images/generations"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.ppio.com/v3/bytedance-cn/api/v3/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

参数及使用方式与火山方舟图片生成 API 一致，详细参数说明请参考：火山方舟图片生成 API。

一、概述

本文档说明 Seedream 5.0 Pro 和 Seedream 5.0 Flash 图片生成接口的调用方式、请求参数、响应结构和计费规则。本接口为同步接口：请求返回时即包含生成结果，不需要轮询。两个模型共用同一个接口，请求体中的 model 决定使用的模型；支持文生图、图生图、多图融合和图层拆分。

1.1 接口地址

操作	接口
生成图片	`POST /v3/bytedance-cn/api/v3/images/generations`

其中 {api_domain} 为平台为您提供的 API 域名，完整地址为 https://{api_domain} 加上表中路径。

1.2 鉴权

所有请求都需要携带平台 API Key，并指定 JSON 内容类型：

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

1.3 支持模型

模型	支持场景	说明
`doubao-seedream-5-0-pro-260628`	文生图、单图生图、多图融合、图层拆分	生成质量更高；按输出图片像素分档计费，额外参考图单独计费；支持 `optimize_prompt_options.mode` 取 `fast`
`doubao-seedream-5-0-flash-260915`	文生图、单图生图、多图融合、图层拆分	生成速度更快；每张输出图片单价相同，输入图片不计费

两个模型的接口、鉴权、请求与响应结构相同，差异在于 model 取值和计费方式。两者都不支持组图生成和流式输出。

二、调用图片生成

参数说明：火山方舟图片生成 API

2.1 请求示例：文生图

curl -X POST 'https://{api_domain}/v3/bytedance-cn/api/v3/images/generations' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "一只戴着红色围巾的金毛犬，在雪山湖边的自然光下，电影感摄影",
    "size": "2K",
    "response_format": "url",
    "watermark": false
  }'

2.2 请求示例：多图融合

curl -X POST 'https://{api_domain}/v3/bytedance-cn/api/v3/images/generations' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedream-5-0-flash-260915",
    "prompt": "将图1中的人物换上图2中的服装，放在城市夜景中，保持人物特征一致",
    "image": [
      "https://example.com/person.png",
      "https://example.com/outfit.png"
    ],
    "size": "2048x1152",
    "response_format": "url"
  }'

image 传单个字符串即为单图生图；传数组即为多图融合，最多 10 张。

2.3 请求示例：图层拆分

curl -X POST 'https://{api_domain}/v3/bytedance-cn/api/v3/images/generations' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "把人物、背景和标题文字拆成独立图层",
    "image": "https://example.com/poster.png",
    "layer_decomposition": true,
    "size": "auto"
  }'

图层拆分把单张输入图拆成一张底图和最多 16 个可独立编辑的图层。prompt 可选，不传时模型自动识别图片中的主要元素并拆分。

2.4 请求字段

字段	类型	必填	说明
`model`	string	是	`doubao-seedream-5-0-pro-260628` 或 `doubao-seedream-5-0-flash-260915`
`prompt`	string	图片生成时必填；图层拆分时可选	支持中文、英文及多种其他语言；建议中文不超过 300 字、英文不超过 600 词
`image`	string / string[]	图层拆分时必填	参考图 URL 或 Base64 Data URL；限制见 2.6
`layer_decomposition`	boolean	否	默认 `false`；`true` 时开启图层拆分
`size`	string	否	图片生成默认 `2K`，可选 `1K`、`1.5K`、`2K` 或 `宽x高`；图层拆分默认 `auto`，可选 `1K`、`1.5K`、`2K`、`auto`；规则见 2.5
`output_format`	string	否	`jpeg`（默认）或 `png`；图层拆分时只控制底图格式，图层始终为 `png`
`background`	string	否	`opaque`（默认）或 `transparent`；限制见 2.5
`optimize_prompt_options.mode`	string	否	`standard`（默认）；Seedream 5.0 Pro 还支持 `fast`，生成更快、效果略低
`response_format`	string	否	`url`（默认）或 `b64_json`
`watermark`	boolean	否	默认 `true`，在图片右下角添加「AI 生成」水印

2.5 尺寸与组合规则

size 的取值：

场景	可选值	说明
图片生成	`1K`、`1.5K`、`2K`（默认）	由模型结合提示词中的宽高比描述决定实际尺寸，例如 `2K` + 3:2 输出 `2496x1664`
图片生成	`宽x高`	总像素在 921,600（1280x720）到 4,624,220 之间，宽高比在 1/16 到 16 之间
图层拆分	`1K`、`1.5K`、`2K`、`auto`（默认）	只支持档位，不支持 `宽x高`；底图分辨率等于 `size`，各图层分辨率接近 `size` 并保持其在原图中的宽高比

图层拆分 auto 模式下，原始尺寸在 921,600 到 4,624,220 像素之间的底图和图层按原尺寸输出，小于 1K 的按 1K 输出，大于 2K 的按 2K 输出。组合约束：

图层拆分时 image 必填且只能传一张，传多张返回错误。
图层拆分为全有或全无：任一图层生成失败，整个请求失败。
background 为 transparent 时只支持图生图，且只能输入一张带透明通道的图片；输出默认为 png，同时指定 output_format 为 jpeg 会返回错误。
不支持 stream、sequential_image_generation 和 sequential_image_generation_options，传入任一字段返回 400。

2.6 输入图片限制

场景	格式	大小	其他
图片生成	jpeg、png、webp、bmp、tiff、gif、heic、heif	≤ 30 MB	最多 10 张；宽高比 1/16 到 16；宽、高均大于 14 px；总像素 196 到 36,000,000
图层拆分	png、jpeg	≤ 30 MB	只能 1 张；宽高比 1/16 到 16；总像素 262,144（512x512）到 36,000,000

图片 URL 必须可公开访问。Base64 格式为 data:image/<图片格式>;base64,<Base64 编码>，图片格式需小写，如 data:image/png;base64,...。

2.7 响应说明

成功响应示例：

{
  "created": 1793952000,
  "model": "doubao-seedream-5-0-pro-260628",
  "data": [
    {
      "url": "https://example.com/generated-image.jpeg",
      "size": "2496x1664",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "generated_images": 1,
    "input_images": 0,
    "output_tokens": 16224,
    "total_tokens": 16224
  }
}

字段	类型	说明
`created`	integer	创建时间，Unix 时间戳（秒）
`model`	string	本次请求的模型
`data[].url`	string	`response_format` 为 `url` 时返回；24 小时内有效，请及时下载
`data[].b64_json`	string	`response_format` 为 `b64_json` 时返回
`data[].size`	string	实际输出尺寸，格式 `宽x高`；Seedream 5.0 Pro 按它确定价格档位
`data[].output_format`	string	`jpeg` 或 `png`
`data[].z_index`	integer	仅图层拆分返回；底图为 `0`，图层从 `1` 递增，数值越大越靠上
`data[].name` / `data[].description`	string	仅图层拆分返回；图层名称和描述
`data[].bounding_box`	object	仅图层返回（底图不返回）；`absolute` 为底图坐标系下的像素坐标 `[left, top, right, bottom]`，`normalized` 为换算到 0–1000 的坐标
`usage.generated_images`	integer	成功生成的图片数
`usage.input_images`	integer	输入图片数
`usage.output_tokens` / `usage.total_tokens`	integer	输出图片的 token 数，不参与计费

图片生成返回一个 data 项；图层拆分返回多个 data 项（一张底图加多个图层），按 z_index 从小到大叠放即可还原。

三、计费说明

请求费用 = Σ（每张成功输出图片的单价） + 额外参考图费用（仅 Seedream 5.0 Pro）

两个模型都按请求实际生成结果计费，请求返回时完成计费：

项目	Seedream 5.0 Pro	Seedream 5.0 Flash
计费数量	每张成功输出图片计 1 张；图层拆分时底图和每个图层各计 1 张	同左
价格档位	每张输出图片按其 `data[].size` 的像素分档：≤ 2,610,000 像素与 > 2,610,000 像素两档；图层拆分使用单独的图层价格	不分档，所有输出图片单价相同
输入图片	第 1 张免费，从第 2 张起每张计费	不计费
失败请求	未生成图片的请求不产生费用	同左

同一次图层拆分请求的底图和各图层像素不同，可能分别落在两个档位，账单按各档位张数分别累计。图片生成时，1K、1.5K 档的输出通常在 2,610,000 像素以内，2K 档的输出通常超过 2,610,000 像素；以响应中的 data[].size 为准。

3.1 计费与 usage 字段对照

字段	是否参与计费	说明
`data[].size`	是（Seedream 5.0 Pro）	决定每张输出图片的价格档位
`usage.generated_images`	是	成功输出图片数，与计费张数一致
`usage.input_images`	是（Seedream 5.0 Pro）	输入图片数；计费的额外参考图张数为该值减 1
`usage.output_tokens` / `usage.total_tokens`	否	仅供参考

具体单价以您所使用服务的价格页面为准。

四、常见错误

HTTP	场景	处理建议
400	JSON 格式错误；`model` 不在支持列表中；传入 `stream: true` 或组图字段	根据 `metadata.details` 修正请求
400	API Key 缺失	检查 `Authorization: Bearer <API_KEY>` 请求头
400	参数取值不合法，如 `size` 超出范围、图片无法读取	根据 `error.message` 修正请求，错误体见 4.1
403	API Key 无效；余额或预算不足	检查 API Key，或充值、调整预算后重试
429	请求频率超过限制	降低请求频率，并使用退避重试
500	服务端错误	使用 `trace_id` 联系技术支持

4.1 错误响应结构

请求格式、鉴权、余额和模型校验失败时，错误体如下，metadata.trace_id 可用于排查：

{
  "code": 400,
  "reason": "INVALID_REQUEST_BODY",
  "message": "invalid request body",
  "metadata": {
    "details": "body.model must be one of: doubao-seedream-5-0-flash-260915, doubao-seedream-5-0-pro-260628",
    "trace_id": "platform-trace-id"
  }
}

参数取值不合法、图片无法读取或内容审核未通过时，错误体如下，error.code 与 error.message 说明具体原因：

{
  "error": {
    "code": "InvalidParameter",
    "message": "The parameter `size` specified in the request are not valid: image area must be at least 921600 pixels. Request id: ...",
    "param": "size",
    "type": "BadRequest"
  }
}

两种错误体都表示请求未生成图片，不产生费用。

五、使用建议

收到成功响应后立即下载 data[].url，地址 24 小时后失效。
需要控制 Seedream 5.0 Pro 成本时，可使用 1K 或 1.5K 档，输出通常落在 2,610,000 像素以内的低档。
图层拆分时只传一张图片，size 使用档位或 auto，不要传 宽x高。
不要传 stream、sequential_image_generation、sequential_image_generation_options，否则返回 400。
生成较慢时可设置较长的客户端超时（建议 120 秒以上）；超时不代表请求一定未成功，请结合业务侧幂等控制决定是否重试。
对时延敏感的业务，可使用 Seedream 5.0 Flash，或使用 Seedream 5.0 Pro 的 optimize_prompt_options.mode: fast。

六、Python 调用示例

以下示例使用标准 requests 库演示文生图。图生图、多图融合或图层拆分只需在请求体中加入 image、layer_decomposition 等字段。

import os

import requests


api_domain = os.environ["API_DOMAIN"]
api_key = os.environ["PLATFORM_API_KEY"]

payload = {
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "一只戴着红色围巾的金毛犬，在雪山湖边的自然光下，电影感摄影",
    "size": "2K",
    "response_format": "url",
}

response = requests.post(
    f"https://{api_domain}/v3/bytedance-cn/api/v3/images/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=180,
)
response.raise_for_status()
result = response.json()
for item in result["data"]:
    print(item["size"], item["url"])
print(result["usage"])

最后修改于 2026年11月10日

基础

大语言

图像

视频

音频

Seedream

一、概述

1.1 接口地址

1.2 鉴权

1.3 支持模型

二、调用图片生成

2.1 请求示例：文生图

2.2 请求示例：多图融合

2.3 请求示例：图层拆分

2.4 请求字段

2.5 尺寸与组合规则

2.6 输入图片限制

2.7 响应说明

三、计费说明

3.1 计费与 usage 字段对照

四、常见错误

4.1 错误响应结构

五、使用建议

六、Python 调用示例

​一、概述

​1.1 接口地址

​1.2 鉴权

​1.3 支持模型

​二、调用图片生成

​2.1 请求示例：文生图

​2.2 请求示例：多图融合

​2.3 请求示例：图层拆分

​2.4 请求字段

​2.5 尺寸与组合规则

​2.6 输入图片限制

​2.7 响应说明

​三、计费说明

​3.1 计费与 usage 字段对照

​四、常见错误

​4.1 错误响应结构

​五、使用建议

​六、Python 调用示例

一、概述

1.1 接口地址

1.2 鉴权

1.3 支持模型

二、调用图片生成

2.1 请求示例：文生图

2.2 请求示例：多图融合

2.3 请求示例：图层拆分

2.4 请求字段

2.5 尺寸与组合规则

2.6 输入图片限制

2.7 响应说明

三、计费说明

3.1 计费与 usage 字段对照

四、常见错误

4.1 错误响应结构

五、使用建议

六、Python 调用示例