Text-to-Image API Reference

Seedream text-to-image API reference and live Playground — pure text prompts, 1K/2K/3K/4K and exact pixel sizes, three versions on a single endpoint

POST /v1/images/generations

Text-to-Image: generate an image from a text prompt

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

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

The interactive Playground on the right lets you call the API directly. Set Authorization to your API key (format: Bearer sk-xxx), enter a prompt, pick a model and size, and hit send.

Scope: this page covers pure text-to-image (no image field). For reference-image editing, multi-image fusion, or batch sequence generation, see Image Editing — same endpoint, just different parameters.

🖥️ Browser Playground limitation (b64_json mode only)

In the default response_format: "url" mode, the Playground works fine (the response is just a temporary BytePlus TOS link). If you switch to response_format: "b64_json", the response contains a multi-MB base64 string and the browser Playground may show 请求时发生错误: unable to complete request — the request actually succeeded; the browser just can’t render such a long base64 string.

Recommended workflow:

• Just want to view the image? Keep the default url mode — the Playground returns the link directly (remember to download to your own storage within 24 hours).
• Need b64_json? Copy the code sample below and run it locally — the code will decode and save the image to a file automatically.

⚠️ Resolution tiers vary by version

• seedream-5-0-260128 — 2K / 3K only (no 4K)
• seedream-4-5-251128 — 2K / 4K
• seedream-4-0-250828 — 1K / 2K / 4K

Unsupported sizes return 400. Exact pixels must satisfy total ∈ [1280×720, 4096×4096] and aspect ratio ∈ [1/16, 16].

Code Examples

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 (raw 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  # ~15s typical, 4K + hd may reach 30-60s
).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);

Browser JavaScript

{/* Demo only — proxy through your backend in production to avoid leaking the 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;

Parameter Reference

Parameter	Type	Required	Default	Description
model	string	yes	—	seedream-5-0-260128 / seedream-4-5-251128 / seedream-4-0-250828
prompt	string	yes	—	Prompt text. Supports English and Chinese. Be detailed about scene, style, lighting.
size	string	no	2K	Preset tier (varies by version) or exact pixels WxH
response_format	string	no	url	url returns a signed link; b64_json returns a plain base64 string
output_format	string	no	jpeg	5.0 supports png / jpeg; 4.5 / 4.0 only jpeg (pass via extra_body in OpenAI SDK)
n	integer	no	1	Output count per request (recommended ≤ 4, subject to total ≤ 15)
seed	integer	no	random	Seed for reproducibility
watermark	boolean	no	varies	Whether to include the BytePlus watermark (set false for commercial use)
stream	boolean	no	false	Streaming output, useful for long prompts + high resolution

Detailed parameter constraints, allowed values, and examples are visible in the Playground panel on the right. Editing / multi-image parameters (image, sequential_image_generation, etc.) are documented on the Image Editing page.

Response Format

{
  "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 field caveats

• When response_format=url, data[].url is a temporary signed BytePlus TOS URL (typically valid for 24 hours). For production, download immediately to your own storage.
• When response_format=b64_json, data[].b64_json is a plain base64 string, without the data:image/...;base64, prefix. Decode it (base64.b64decode) for file output, or prepend the prefix yourself for browser rendering.
• data[].size reflects the actual output size, which may differ slightly from the requested size after the model’s aspect-ratio normalization.

usage.generated_images reflects the billed image count. Seedream bills per image; output_tokens / total_tokens are observability metrics and do not affect billing.

Authorizations

Authorization · string · header · required

API Key obtained from APIYI Console

Body

application/json

model · enum<string> · default: seedream-5-0-260128 · required

Model ID — pick one

Available options: seedream-5-0-260128, seedream-5-0-lite-260128, seedream-4-5-251128, seedream-4-0-250828

prompt · string · required

Prompt, supports both English and Chinese. Describe scene, style, and lighting in detail for better results.

Example:

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

size · string · default: 2K

Output size. Preset tiers (vary by version):

• 1K (~1024×1024) — 4.0 only
• 2K (~2048×2048) — 5.0 / 4.5 / 4.0
• 3K (~3072×3072) — 5.0 only
• 4K (~4096×4096) — 4.5 / 4.0

Or exact pixel size WxH, total pixels ∈ [1280×720, 4096×4096], aspect ratio ∈ [1/16, 16]

Example:

"2K"

response_format · enum<string> · default: url

url returns a temp signed link (24h validity); b64_json returns plain base64 (no data: prefix)

Available options: url, b64_json

output_format · enum<string> · default: jpeg

Output format. 5.0 supports png/jpeg; 4.5/4.0 only jpeg

Available options: png, jpeg

n · integer · default: 1

Number of images per request. Recommended ≤ 4. Subject to overall input+output ≤ 15. For batch sequence generation use sequential_image_generation

Required range: 1 <= x <= 4

seed · integer

Random seed for reproducibility. Omit for random

Example:

42

watermark · boolean · default: false

Whether to include the BytePlus watermark. Set to false for commercial use

stream · boolean · default: false

Enable streaming output. Useful for long prompts and high-resolution generation

Response

200

application/json

Image generated successfully

model · string

Example:

"seedream-5-0-260128"

created · integer

Unix timestamp

Example:

1768518000

data · object[]

Show child attributes

usage · object

Show child attributes