文生图 API 参考

Seedream 文生图 API 参考与在线调试 — 纯文本提示词出图，支持 1K/2K/3K/4K 与精确像素，三版本统一端点

POST /v1/images/generations

文生图：根据文本提示词生成图片

cURL

curl --request POST \
  --url https://api.apiyi.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "model": "seedream-5-0-260128",
  "prompt": "A modern tech product launch poster, sleek smartphone on gradient background, text: 'Innovation 2026', ultra detailed, professional"
}
EOF

import requests

url = "https://api.apiyi.com/v1/images/generations"

payload = {
    "model": "seedream-5-0-260128",
    "prompt": "A modern tech product launch poster, sleek smartphone on gradient background, text: 'Innovation 2026', ultra detailed, professional"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'seedream-5-0-260128',
    prompt: 'A modern tech product launch poster, sleek smartphone on gradient background, text: \'Innovation 2026\', ultra detailed, professional'
  })
};

fetch('https://api.apiyi.com/v1/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.apiyi.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'seedream-5-0-260128',
    'prompt' => 'A modern tech product launch poster, sleek smartphone on gradient background, text: \'Innovation 2026\', ultra detailed, professional'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.apiyi.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"seedream-5-0-260128\",\n  \"prompt\": \"A modern tech product launch poster, sleek smartphone on gradient background, text: 'Innovation 2026', ultra detailed, professional\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"seedream-5-0-260128\",\n  \"prompt\": \"A modern tech product launch poster, sleek smartphone on gradient background, text: 'Innovation 2026', ultra detailed, professional\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apiyi.com/v1/images/generations")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"seedream-5-0-260128\",\n  \"prompt\": \"A modern tech product launch poster, sleek smartphone on gradient background, text: 'Innovation 2026', ultra detailed, professional\"\n}"

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

200

{
  "model": "seedream-5-0-260128",
  "created": 1768518000,
  "data": [
    {
      "url": "https://ark-content-generation-v2-ap-southeast-1.tos-ap-southeast-1.bytepluses.com/seedream-5-0/.../image.png",
      "b64_json": "<string>",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 6240,
    "total_tokens": 6240
  }
}

右侧的交互式 Playground 支持直接在线调试。请在 Authorization 中填入你的 API Key（格式：Bearer sk-xxx），输入 prompt、选择 model / size 后一键发送即可。

场景说明：本页用于「纯文本提示词生成图片」——不传 image 字段。如需基于参考图编辑、多图融合或批量序列生成，请使用 图片编辑接口（同一端点，多传 image 参数）。

🖥️ 浏览器 Playground 限制（仅 b64_json 模式）

默认 response_format: "url" 模式下 Playground 工作正常（响应只是一个 BytePlus TOS 临时链接）。如果你切换成 response_format: "b64_json"，响应会包含数 MB 的 base64 字符串，浏览器 Playground 可能弹出 请求时发生错误: unable to complete request ——实际请求已经成功，只是浏览器无法显示这么长的 base64。

推荐做法：

• 只想看图：保持默认 url 模式，Playground 会直接返回链接（注意 24 小时内下载到自己的存储）。
• 真的需要 b64_json：复制下方”代码示例”到本地运行，代码会自动解码并把图片保存为本地文件。

⚠️ 各版本支持的分辨率档位不同

• seedream-5-0-pro-260628 —— 预设 1K / 2K + 精确 WxH 总像素 ≤ 4.19M（16:9 最长边可达 2720×1530，实测可用；无 3K/4K 预设；不支持 sequential_image_generation / stream，传入即 400；约 2 分钟出图）
• seedream-5-0-260128 —— 仅 2K / 3K（无 4K）
• seedream-4-5-251128 —— 2K / 4K
• seedream-4-0-250828 —— 1K / 2K / 4K

不支持的尺寸会直接返回 400。精确像素总像素需 ∈ [1280×720, 4096×4096]，宽高比 ∈ [1/16, 16]。

图片 API 全部为同步调用：没有异步任务 ID，客户端断开连接结果即丢失、但请求仍会计费。请为本模型设置足够大的 timeout，详见 图片 API 调用须知与最佳实践。

​

代码示例

​

Python（OpenAI SDK 直连）

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.apiyi.com/v1"
)

resp = client.images.generate(
    model="seedream-5-0-260128",
    prompt="A modern tech product launch poster with bold typography, sleek smartphone on gradient background, text: 'Innovation 2026', ultra detailed, professional",
    size="2K",
    response_format="url",
    extra_body={
        "output_format": "png",
        "watermark": False,
    }
)

print(resp.data[0].url)

​

Python（原生 requests）

import requests

API_KEY = "sk-your-api-key"

response = requests.post(
    "https://api.apiyi.com/v1/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "model": "seedream-5-0-260128",
        "prompt": "A serene Japanese garden with cherry blossoms, koi pond, traditional wooden bridge, golden hour, ultra detailed",
        "size": "2K",
        "response_format": "url",
        "watermark": False
    },
    timeout=60  # 单图约 15 秒，4K + hd 可达 30-60 秒
).json()

print(response["data"][0]["url"])

​

cURL

curl -X POST "https://api.apiyi.com/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-260128",
    "prompt": "A futuristic cityscape at night with neon lights and flying vehicles, cyberpunk style, high detail",
    "size": "2K",
    "response_format": "url",
    "watermark": false
  }'

​

Node.js（原生 fetch）

const resp = await fetch('https://api.apiyi.com/v1/images/generations', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer sk-your-api-key'
    },
    body: JSON.stringify({
        model: 'seedream-5-0-260128',
        prompt: 'Minimalist line-art logo of a cat, monochrome, vector style',
        size: '2K',
        response_format: 'url',
        output_format: 'png',
        watermark: false
    })
});

const { data } = await resp.json();
console.log(data[0].url);

​

浏览器 JavaScript

{/* 仅作演示，生产请走后端代理避免 Key 泄露 */}
const resp = await fetch('https://api.apiyi.com/v1/images/generations', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer sk-your-api-key'
    },
    body: JSON.stringify({
        model: 'seedream-5-0-260128',
        prompt: 'Watercolor northern lights over snowy mountains',
        size: '2K'
    })
});

const { data } = await resp.json();
document.getElementById('img').src = data[0].url;

​

参数说明速查

参数	类型	必填	默认	说明
model	string	是	—	seedream-5-0-260128 / seedream-4-5-251128 / seedream-4-0-250828 / seedream-5-0-pro-260628（专业版，$0.12/次）
prompt	string	是	—	提示词，支持中英文，建议详细描述场景、风格、光线
size	string	否	2K	预设档位（各版本不同）或精确像素 WxH
response_format	string	否	url	url 返回图片链接；b64_json 返回纯 base64 字符串
output_format	string	否	jpeg	5.0 支持 png / jpeg；4.5 / 4.0 仅 jpeg（OpenAI SDK 中通过 extra_body 传入）
n	integer	—	—	⚠️ 上游不支持此参数：传入会被静默忽略，仍只返回 1 张、按 1 张计费。多图输出请用 sequential_image_generation（按实际张数计费），见 图片编辑接口
seed	integer	—	—	⚠️ 官方仅 seedream-3-0-t2i 支持该参数，当前 4.x / 5.x 系列传入不生效
watermark	boolean	否	见各版本默认	是否输出水印（建议显式 false 商用）
stream	boolean	否	false	流式输出，适合长 prompt + 高分辨率

详细的参数约束、可选值、示例请查看右侧 Playground 中的字段说明，所有 enum 字段均支持下拉选择。编辑/多图相关参数（image、sequential_image_generation 等）见 图片编辑接口。

​

响应格式

{
  "model": "seedream-5-0-260128",
  "created": 1768518000,
  "data": [
    {
      "url": "https://ark-content-generation-v2-ap-southeast-1.tos-ap-southeast-1.bytepluses.com/seedream-5-0/.../image.png",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 6240,
    "total_tokens": 6240
  }
}

⚠️ 响应字段陷阱

• response_format=url 模式下，data[].url 是 BytePlus TOS 临时签名 URL，有时效性（通常 24 小时内有效），生产场景建议拿到后立即下载到自己的存储
• response_format=b64_json 模式下，data[].b64_json 是 纯 base64 字符串，不含 data:image/...;base64, 前缀，客户端需 base64.b64decode 写文件，或浏览器渲染时自行拼前缀
• data[].size 字段反映实际输出尺寸，可能与请求的 size 略有差异（模型按比例约束）

usage 字段反映本次实际计费的张数（generated_images）。Seedream 按张计费，output_tokens / total_tokens 仅用于性能观测，不参与账单核算。

授权

Authorization · string · header · 必填

在 API易控制台获取的 API Key

请求体

application/json

model · enum<string> · 默认值: seedream-5-0-260128 · 必填

模型 ID

可用选项: seedream-5-0-260128, seedream-5-0-lite-260128, seedream-4-5-251128, seedream-4-0-250828, seedream-5-0-pro-260628

prompt · string · 必填

提示词，支持中英文。建议详细描述场景、风格、光线

示例:

"A serene Japanese garden with cherry blossoms, koi pond, traditional bridge, golden hour, ultra detailed"

size · string · 默认值: 2K

输出尺寸。预设档位（各版本支持不同）：

• 1K（约 1024×1024）：仅 4.0
• 2K（约 2048×2048）：5.0 / 4.5 / 4.0
• 3K（约 3072×3072）：仅 5.0
• 4K（约 4096×4096）：4.5 / 4.0

或精确像素 WxH，总像素 ∈ [1280×720, 4096×4096]，宽高比 ∈ [1/16, 16]

示例:

"2K"

response_format · enum<string> · 默认值: url

返回格式。url 返回临时签名链接（24 小时有效）；b64_json 返回纯 base64 字符串（不带 data: 前缀）

可用选项: url, b64_json

output_format · enum<string> · 默认值: jpeg

输出格式。5.0 支持 png / jpeg；4.5 / 4.0 仅 jpeg

可用选项: png, jpeg

seed · integer

随机种子。注意：官方仅 seedream-3-0-t2i 支持，当前 4.x / 5.x 系列传入不生效

示例:

42

watermark · boolean · 默认值: false

是否输出带 BytePlus 水印的图片。商用场景建议显式 false

stream · boolean · 默认值: false

是否启用流式输出。长 prompt + 高分辨率场景建议开启

响应

200

application/json

成功生成图片

model · string

本次实际调用的模型 ID

示例:

"seedream-5-0-260128"

created · integer

Unix 时间戳

示例:

1768518000

data · object[]

生成结果数组（文生图通常 1 个元素）

Show child attributes

usage · object

本次调用计费张数与 token 用量

Show child attributes