Text-to-Image API Reference - API易文档中心

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": [
    {
      "b64_json": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "created": 1778037127,
  "usage": {
    "input_tokens": 98,
    "output_tokens": 1185,
    "total_tokens": 1283
  }
}

POST

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": [
    {
      "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.

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

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

GPT-Image-2-VIP Overview Image Editing API Reference

​Code Examples

​Python

​cURL

​Node.js

​OpenAI SDK (Python, recommended)

​Parameters

​Response Format

​Related Resources

Model Overview (full size table)

Chat API

Image Editing API

Sister model gpt-image-2-all

Authorizations

Body

Response

Code Examples

Python

cURL

Node.js

OpenAI SDK (Python, recommended)

Parameters

Response Format

Related Resources