Text-to-Image API Reference

gpt-image-2-vip text-to-image API reference and interactive playground — generate images from text + size, $0.03/image flat across all sizes

POST /v1/images/generations

Text-to-Image: generate at an explicit size 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 '
{
  "model": "gpt-image-2-vip",
  "prompt": "Cinematic landscape, old lighthouse by the sea at dusk, photorealistic"
}
'

200

{
  "data": [
    {
      "b64_json": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "created": 1778037127,
  "usage": {
    "input_tokens": 98,
    "output_tokens": 1185,
    "total_tokens": 1283
  }
}

The interactive Playground on the right supports direct online testing. Enter your API Key in the Authorization field (format: Bearer sk-xxx), set prompt and size, then click send.

Scope: This page is for text-to-image generation. Just enter a prompt and size — no image upload required. To edit or fuse existing images, use the Image Editing endpoint.

Difference vs gpt-image-2-all: identical call structure, just one extra size field. If you don’t need to lock dimensions and want fastest output, use gpt-image-2-all instead.

🖥️ Browser Playground limitation (default b64_json mode)

This endpoint defaults to response_format: "b64_json", so the response carries 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 in the Playground? Pass "response_format": "url" explicitly — the response is a single R2 link and renders fine.
• Want base64? Copy the code sample below and run it locally.

⚠️ Key parameter notes

• size: pass auto to let the model choose (vip tends to converge on a relatively fixed/stable size for a given prompt), or pick one of the 30 supported sizes (10 ratios × 1K Fast / 2K Recommended / 4K Detail — see the full size table on the overview page) for strict locking. Use lowercase ASCII x, e.g., 2048x1360, 3840x2160 — never × or uppercase X.
• quality: ❌ rejected — do not pass.
• n: ❌ rejected — single image per call. Sending n=3 charges 3× but still returns 1 image. Drop the field.
• aspect_ratio: ❌ rejected — ratio is determined by size.

Code Examples

Python

import requests

API_KEY = "sk-your-api-key"

response = requests.post(
    "https://api.apiyi.com/v1/images/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "gpt-image-2-vip",
        "prompt": "Cinematic landscape, old lighthouse by the sea at dusk, photorealistic",
        "size": "2048x1152",          # 16:9 2K Recommended
        "response_format": "url"
    },
    timeout=300  # conservative; absorbs long-tail and image download
).json()

image_url = response["data"][0]["url"]
print(image_url)

4K Detail tier example (wallpaper / print):

import requests

response = requests.post(
    "https://api.apiyi.com/v1/images/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "gpt-image-2-vip",
        "prompt": "Desktop wallpaper, cyberpunk city night, neon signs, wet pavement reflections",
        "size": "3840x2160",          # 16:9 4K Detail
        "response_format": "b64_json"
    },
    timeout=300
).json()

# b64_json already includes "data:image/png;base64," prefix — use directly as <img src>
data_url = 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-vip",
    "prompt": "Product shot of a white ceramic mug on a gray desk, soft natural light",
    "size": "2048x1360",
    "response_format": "url"
  }'

Node.js

const API_KEY = "sk-your-api-key";

const response = await fetch(
  "https://api.apiyi.com/v1/images/generations",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "gpt-image-2-vip",
      prompt: "1:1 square logo, minimalist cat line art",
      size: "2048x2048",        // 1:1 2K Recommended
      response_format: "b64_json"
    })
  }
);

const data = await response.json();
// b64_json already prefixed — use directly as <img src>
document.getElementById("result").src = data.data[0].b64_json;

OpenAI SDK (Python, recommended)

from openai import OpenAI

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

resp = client.images.generate(
    model="gpt-image-2-vip",
    prompt="Ink wash landscape painting, traditional Chinese style, vertical composition",
    size="1536x2048",        # 3:4 2K Portrait
)
print(resp.data[0].url)

Parameters

Parameter	Type	Required	Description
model	string	Yes	Fixed at gpt-image-2-vip
prompt	string	Yes	Prompt — describe content, style, lighting, etc.
size	string	Strongly recommended	Output size: auto (model decides — vip stays relatively fixed for a given prompt) or one of the 30 sizes; format WIDTHxHEIGHT (lowercase x); omitting the field is equivalent to auto
response_format	string	No	b64_json (default, returns base64 data URL) or url (returns R2 CDN link)

Size cheat-sheet — these cover most cases:

• E-commerce hero shots: 2048x1360 (3:2 2K) / 2048x2048 (1:1 2K)
• Vertical posters: 1536x2048 (3:4 2K) / 2480x3312 (3:4 4K)
• Video thumbnails: 2048x1152 (16:9 2K) / 3840x2160 (16:9 4K)
• Story / phone wallpapers: 1152x2048 (9:16 2K) / 2160x3840 (9:16 4K)

Full 30-size table: overview page.

Response Format

data[0] returns either url or b64_json — never both (depends on response_format). This endpoint defaults to b64_json.

b64_json mode (default):

{
  "data": [
    {
      "b64_json": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "created": 1778037127,
  "usage": {
    "input_tokens": 98,
    "output_tokens": 1185,
    "total_tokens": 1283
  }
}

url mode (requires explicit "response_format": "url", R2 CDN globally accelerated):

{
  "data": [
    {
      "url": "https://r2cdn.copilotbase.com/r2cdn2/0e82148a-bec0-4b42-bbca-117c6b42581b.png"
    }
  ],
  "created": 1778037331,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 2074,
    "total_tokens": 2104
  }
}

Compatibility note: the b64_json field already includes the data:image/png;base64, prefix. Use it directly as <img src> or write to a file — do not prepend data:image/...;base64, again. This differs from some legacy OpenAI-compatible models.

Related Resources

Model Overview (full size table)

Complete 30-size table, pricing, technical specs

Chat API

Chat Completions format, accepts online URLs directly

Image Editing API

/v1/images/edits multi-image fusion and editing

Sister model gpt-image-2-all

Same call format when you don’t need locked size — faster output (~30–60s)

Authorizations

Authorization · string · header · required

API Key from the API易 Console

Body

application/json

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

Model name, fixed to gpt-image-2-vip

Available options: gpt-image-2-vip

prompt · string · required

Prompt — describe content, style, lighting, etc.

Example:

"Cinematic landscape, old lighthouse by the sea at dusk, photorealistic"

size · enum<string>

Output size. Pass auto to let the model decide (vip tends to converge on a relatively fixed size for a given prompt), or pick one of the 30 supported sizes (10 ratios × 1K Fast / 2K Recommended / 4K Detail) to lock it strictly. Format: WIDTHxHEIGHT with lowercase ASCII x, e.g., 2048x1360, 3840x2160. Flat $0.03/image across all tiers.

Available options: auto, 1280x1280, 848x1280, 1280x848, 960x1280, 1280x960, 1024x1280, 1280x1024, 720x1280, 1280x720, 1280x544, 2048x2048, 1360x2048, 2048x1360, 1536x2048, 2048x1536, 1632x2048, 2048x1632, 1152x2048, 2048x1152, 2048x864, 2880x2880, 2336x3520, 3520x2336, 2480x3312, 3312x2480, 2560x3216, 3216x2560, 2160x3840, 3840x2160, 3840x1632

Example:

"2048x1152"

response_format · enum<string> · default: b64_json

Response format. b64_json returns a base64 string already prefixed with a data URL header (default); url returns an R2 CDN link

Available options: b64_json, url

Response

200

application/json

Image successfully generated. Defaults to base64 in data[0].b64_json — url is not returned in the same response.

Image generation response. data[0] returns either url or b64_json, never both (depends on response_format; this endpoint defaults to b64_json).

data · object[]

Result array (this model returns 1 image per call)

Show child attributes

created · integer

Unix timestamp (seconds)

usage · object

Token usage statistics

Show child attributes