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"
}
'

import requests

url = "https://api.apiyi.com/v1/images/generations"

payload = {
    "model": "gpt-image-2-vip",
    "prompt": "Cinematic landscape, old lighthouse by the sea at dusk, photorealistic"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'gpt-image-2-vip',
    prompt: 'Cinematic landscape, old lighthouse by the sea at dusk, photorealistic'
  })
};

fetch('https://api.apiyi.com/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apiyi.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'gpt-image-2-vip',
    'prompt' => 'Cinematic landscape, old lighthouse by the sea at dusk, photorealistic'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apiyi.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"gpt-image-2-vip\",\n  \"prompt\": \"Cinematic landscape, old lighthouse by the sea at dusk, photorealistic\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"gpt-image-2-vip\",\n  \"prompt\": \"Cinematic landscape, old lighthouse by the sea at dusk, photorealistic\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apiyi.com/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"gpt-image-2-vip\",\n  \"prompt\": \"Cinematic landscape, old lighthouse by the sea at dusk, photorealistic\"\n}"

response = http.request(request)
puts response.read_body

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

This endpoint returns a base64 string (b64_json) by default, which can be several MB, so 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: copy the code sample below and run it locally — it decodes the image and saves it to a file automatically.

All image APIs are synchronous — there is no task ID to poll, and if your client disconnects the result is lost while the request is still billed. Set a generous timeout for this model; see Image API Essentials & Best Practices.

⚠️ 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.
• response_format: omitting it returns base64 (raw, no prefix, verified 2026-07); pass "url" for an image URL. Businesses that depend on URL output should switch their token to the image2_OSS group for deterministic URL output with no base64 fallback.

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"     # defaults to base64; explicit response_format needed to read the url field
    },
    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
    },
    timeout=300
).json()

# Verified 2026-07: b64_json is raw base64 (no data: prefix); earlier versions included the prefix — a check is safest
import base64
b64 = response["data"][0]["b64_json"]
if b64.startswith("data:"):
    b64 = b64.split(",", 1)[1]
with open("wallpaper.png", "wb") as f:
    f.write(base64.b64decode(b64))

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"
  }'

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
    })
  }
);

const data = await response.json();
// Verified raw base64 (no data: prefix) — prepend before rendering; earlier versions included the prefix, so check first
let b64 = data.data[0].b64_json;
if (!b64.startsWith("data:")) b64 = `data:image/png;base64,${b64}`;
document.getElementById("result").src = b64;

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

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

Returns base64 by default (data[0].b64_json, raw base64 without prefix, verified 2026-07). To get an image URL instead, pass response_format: "url" explicitly; businesses that depend on URL output should switch their token’s group to image2_OSS for stable URL output with no base64 fallback. data[0] returns either url or b64_json — never both.

b64_json mode (default):

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

url mode (pass response_format: "url" explicitly; use the image2_OSS group if you depend on URLs — 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: verified July 2026 — the b64_json field is raw base64 without the data: prefix; decode it to write a file, or prepend the prefix yourself before rendering. Earlier versions did include the prefix, so always run a startsWith('data:') check first to handle both shapes.

Related Resources

Model Overview (full size table)

Complete 30-size table, pricing, technical specs

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

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. Returns base64 by default (data[0].b64_json); to get a url, switch to the image2_OSS group with response_format=url. data[0] returns either url or b64_json, never both.

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