跳转到主要内容
POST
/
v1
/
images
/
generations
文生图：根据文本提示词生成图片
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
{
  "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
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt

Use this file to discover all available pages before exploring further.

右侧的交互式 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-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]。

​
代码示例

​
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;

​
参数说明速查

参数类型必填默认说明
modelstring是—seedream-5-0-260128 / seedream-4-5-251128 / seedream-4-0-250828
promptstring是—提示词，支持中英文，建议详细描述场景、风格、光线
sizestring否2K预设档位（各版本不同）或精确像素 WxH
response_formatstring否urlurl 返回图片链接；b64_json 返回纯 base64 字符串
output_formatstring否jpeg5.0 支持 png / jpeg；4.5 / 4.0 仅 jpeg（OpenAI SDK 中通过 extra_body 传入）
ninteger否1一次输出张数（建议 ≤ 4，受单次 ≤ 15 总约束）
seedinteger否随机随机种子，固定可复现
watermarkboolean否见各版本默认是否输出水印（建议显式 false 商用）
streamboolean否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
​
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
​
n
integer
默认值:1

一次输出张数。建议 ≤ 4，受单次请求 输入+输出 ≤ 15 总约束。如需批量序列生成请用 sequential_image_generation

必填范围: 1 <= x <= 4
​
seed
integer

随机种子，固定值可复现相同输出。不传则每次随机

示例:

42

​
watermark
boolean
默认值:false

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

​
stream
boolean
默认值:false

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

响应

成功生成图片

​
model
string

本次实际调用的模型 ID

示例:

"seedream-5-0-260128"

​
created
integer

Unix 时间戳

示例:

1768518000

​
data
object[]

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

​
usage
object

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