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

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

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-pro-260628 — presets 1K / 2K plus exact WxH up to 4.19M total pixels (at 16:9 the longest edge reaches 2720×1530, verified; no 3K/4K presets; sequential_image_generation / stream not accepted — passing them returns 400; ~2 min per image)
• 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].

All image APIs are synchronous — there is no task ID to poll, and if your client disconnects the result is lost while the request is still billed. Set a generous timeout for this model; see Image API Essentials & Best Practices.

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 / seedream-5-0-pro-260628 (pro tier, $0.12/request)
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	—	—	⚠️ Not supported upstream: the parameter is silently ignored — you still get 1 image and are billed for 1. For multi-image output use sequential_image_generation (billed per generated image), see Image Editing
seed	integer	—	—	⚠️ Officially supported only by seedream-3-0-t2i; ignored by the current 4.x / 5.x models
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

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

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

seed · integer

Random seed. Note: officially supported only by seedream-3-0-t2i; ignored by the current 4.x / 5.x models

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