Skip to main content
POST
/
v1
/
images
/
generations
Text-to-Image: generate at an explicit size from a 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-vip",
  "prompt": "Cinematic landscape, old lighthouse by the sea at dusk, photorealistic"
}
'
{
  "data": [
    {
      "url": "https://r2cdn.copilotbase.com/r2cdn2/00aaa9fb-756c-4119-a4a0-4a44fc75152b.png",
      "b64_json": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt

Use this file to discover all available pages before exploring further.

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 (b64_json mode only)In the default response_format: "url" mode, the Playground works fine (the response is just an R2 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.
  • Need b64_json? Copy the code sample below and run it locally.
⚠️ Key parameter notes
  • size: must be one of the 30 supported sizes (10 ratios × 1K Fast / 2K Recommended / 4K Detail — see the full size table on the overview page). 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;

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

ParameterTypeRequiredDescription
modelstringYesFixed at gpt-image-2-vip
promptstringYesPrompt — describe content, style, lighting, etc.
sizestringStrongly recommendedOutput size from the 30-size set; format WIDTHxHEIGHT (lowercase x); falls back to a default tier if omitted
response_formatstringNourl (default, returns R2 CDN link) or b64_json
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

url mode (default, R2 CDN globally accelerated): 
{
    "data": [
        {
            "url": "https://r2cdn.copilotbase.com/r2cdn2/00aaa9fb-756c-4119-a4a0-4a44fc75152b.png"
        }
    ]
}
b64_json mode (requires explicit "response_format": "b64_json"): 
{
    "data": [
        {
            "b64_json": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
        }
    ]
}
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.

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 (~30s)

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, picked from the 30-size set (10 ratios × 1K Fast / 2K Recommended / 4K Detail). Format: WIDTHxHEIGHT with lowercase ASCII x, e.g., 2048x1360, 3840x2160. Flat $0.03/image across all tiers.

Available options:
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:url

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

Available options:
url,
b64_json

Response

Image successfully generated

​
data
object[]

Result array (this model returns 1 image per call)