Skip to main content
POST
/
v1
/
images
/
generations
Text-to-Image: generate image from text prompt
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",
  "size": "2048x1152",
  "quality": "high",
  "output_format": "jpeg",
  "output_compression": 85
}
'
{
  "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.
⚠️ 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

ParamTypeRequiredDefaultDescription
modelstringYes—Fixed: gpt-image-2
promptstringYes—Prompt, supports both Chinese and English
sizestringNoautoOutput size — preset or constraint-satisfying custom
qualitystringNoautolow / medium / high / auto
output_formatstringNopngpng / jpeg / webp
output_compressionintNo—0–100, only for jpeg / webp
backgroundstringNoautoopaque / auto (not supported: transparent)
moderationstringNoautoauto / low (low-strength moderation)
nintNo1Only 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

Image generated successfully

​
created
integer

Unix timestamp

Example:

1776832476

​
data
object[]

Generation results (this model returns 1 image per call)

​
usage
object

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