Text-to-Image API Reference

gpt-image-2 text-to-image API reference and live testing — any valid resolution (incl. 4K), token-billed

POST /v1/images/generations

Text-to-Image: generate image from text prompt

cURL

curl --request POST \
  --url https://api.apiyi.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt-image-2",
  "prompt": "Cyberpunk city at night, neon sign closeup, cinematic frame"
}
'

200

{
  "created": 1776832476,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 6240,
    "total_tokens": 6282
  }
}

The interactive Playground on the right supports live testing. Fill in your API Key in Authorization (format: Bearer sk-xxx), enter a prompt, choose size / quality, and send.

Use case: This page is for “text-to-image”. Just enter a prompt — no image upload needed. For reference image editing, multi-image fusion, or mask inpainting, use the Image Edit endpoint.

🖥️ Browser Playground limitation (important)

This endpoint returns a raw base64 string (typically several MB) in the response. Due to browser rendering limits, the Playground on the right may show 请求时发生错误: unable to complete request after the response arrives — the request actually succeeded; the browser just can’t render such a long base64 string.

Recommended workflow (beginner-friendly):

• Copy the Python / Node.js / cURL sample below and run it locally. The code automatically base64.b64decodes the response and writes the image to a file.
• If you must use the in-browser Playground, set size to the smallest tier (e.g. 1024x1024) and quality to low to shrink the response.

⚠️ Unsupported parameters

• input_fidelity — gpt-image-2 forces high-fidelity; passing this returns 400. When migrating from 1.5, just remove the line.
• background: "transparent" — Transparent background is not supported. Use opaque or post-process for transparency.

Outputs above 2560×1440 remain experimental. For production, prefer presets: 2048x1152 / 2048x2048 / 3840x2160.

Code Examples

Python (OpenAI SDK)

from openai import OpenAI
import base64

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

resp = client.images.generate(
    model="gpt-image-2",
    prompt="Cyberpunk city at night, neon sign closeup, cinematic frame",
    size="2048x1152",
    quality="high",
    output_format="jpeg",
    output_compression=85
)

# b64_json is raw base64 (no prefix) — decode and write to file
with open("out.jpg", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

Python (Raw requests)

import requests
import base64

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": "gpt-image-2",
        "prompt": "Landscape 2K seaside lighthouse at sunset, cinematic frame",
        "size": "2048x1152",
        "quality": "high"
    },
    timeout=360  # high + 2K/4K can run 3-5 min; ~120s defaults will frequently false-timeout
).json()

with open("out.png", "wb") as f:
    f.write(base64.b64decode(response["data"][0]["b64_json"]))

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": "gpt-image-2",
    "prompt": "Orange tabby cat with sunglasses at a seaside bar, cinematic",
    "size": "2048x1152",
    "quality": "high",
    "output_format": "jpeg",
    "output_compression": 85
  }'

Node.js (Native fetch)

import fs from 'node:fs';

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: 'gpt-image-2',
        prompt: 'Minimalist line-art cat logo',
        size: '1024x1024',
        quality: 'medium'
    })
});

const { data } = await resp.json();
// b64_json is raw base64 — decode manually
fs.writeFileSync('logo.png', Buffer.from(data[0].b64_json, 'base64'));

Browser JavaScript (Direct render)

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: 'gpt-image-2',
        prompt: 'Watercolor-style Nordic aurora',
        size: '1536x1024',
        quality: 'high'
    })
});

const { data } = await resp.json();
// Browser rendering needs the data URL prefix prepended manually
document.getElementById('img').src = `data:image/png;base64,${data[0].b64_json}`;

Parameter Reference

Param	Type	Required	Default	Description
model	string	Yes	—	Fixed: gpt-image-2
prompt	string	Yes	—	Prompt, supports both Chinese and English
size	string	No	auto	Output size — preset or constraint-satisfying custom
quality	string	No	auto	low / medium / high / auto
output_format	string	No	png	png / jpeg / webp
output_compression	int	No	—	0–100, only for jpeg / webp
background	string	No	auto	opaque / auto (not supported: transparent)
moderation	string	No	auto	auto / low (low-strength moderation)
n	int	No	1	Only 1 supported

Detailed constraints, allowed values, and examples are visible in the Playground on the right — all enum fields support dropdown selection.

Response Format

{
    "created": 1776832476,
    "data": [
        {
            "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
        }
    ],
    "usage": {
        "input_tokens": 42,
        "output_tokens": 6240,
        "total_tokens": 6282
    }
}

⚠️ b64_json is raw base64, without the data:image/...;base64, prefix. Client must:

• Write file: base64.b64decode(b64_str) → write to disk
• Browser render: prepend data:image/png;base64, manually

This differs from gpt-image-2-all which already includes the prefix. Be careful.

The usage field reflects actual billed tokens for this call. Billing is the sum of input text + input image + output image tokens. Use the pricing table on the overview page to estimate cost.

Authorizations

Authorization · string · header · required

API Key obtained from APIYI Console

Body

application/json

model · enum<string> · default: gpt-image-2 · required

Model name, fixed as gpt-image-2

Available options: gpt-image-2

prompt · string · required

Prompt text. Supports both Chinese and English. Place scene description at the front for better adherence.

Example:

"Cyberpunk city at night, neon sign closeup, cinematic frame"

size · string · default: auto

Output size. Presets: 1024x1024 / 1536x1024 / 1024x1536 / 2048x2048 / 2048x1152 / 3840x2160 / 2160x3840. Also accepts any valid custom size (max edge ≤ 3840, both multiples of 16, ratio ≤ 3:1, total pixels 0.65–8.3MP).

Example:

"2048x1152"

quality · enum<string> · default: auto

Quality tier. low (sketches/batch), medium (daily), high (final/fine text), auto (default)

Available options: auto, low, medium, high

output_format · enum<string> · default: png

Output format

Available options: png, jpeg, webp

output_compression · integer

Output compression (0–100), only effective for jpeg/webp

Required range: 0 <= x <= 100

Example:

85

background · enum<string> · default: auto

Background mode. auto (default) or opaque. Not supported: transparent

Available options: auto, opaque

moderation · enum<string> · default: auto

Moderation strength. auto (default) or low

Available options: auto, low

n · enum<integer> · default: 1

Number of images. This model only supports 1

Available options: 1

Response

200

application/json

Image generated successfully

created · integer

Unix timestamp

Example:

1776832476

data · object[]

Generation results (this model returns 1 image per call)

Show child attributes

usage · object

Token usage for this call (used for token-based billing)

Show child attributes