Text-to-Image API Reference

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.

⚠️ 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

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

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

Basics

Basic API

Image API

Video API

Multimodal Understanding API

Text API

Code Examples

Python (OpenAI SDK)

Python (raw requests)

cURL

Node.js (fetch)

Browser JavaScript

Parameter Reference

Response Format

Authorizations

Body

Response

Basics

Basic API

Image API

Video API

Multimodal Understanding API

Text API

​Code Examples

​Python (OpenAI SDK)

​Python (raw requests)

​cURL

​Node.js (fetch)

​Browser JavaScript

​Parameter Reference

​Response Format

Authorizations

Body

Response

Code Examples

Python (OpenAI SDK)

Python (raw requests)

cURL

Node.js (fetch)

Browser JavaScript

Parameter Reference

Response Format