Text-to-Image API Reference

gpt-image-2 text-to-image API reference and live testing — any valid resolution (incl. 4K), token-billed

POST /v1/images/generations

Text-to-Image: generate image from 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",
  "prompt": "Cyberpunk city at night, neon sign closeup, cinematic frame"
}
'

import requests

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

payload = {
    "model": "gpt-image-2",
    "prompt": "Cyberpunk city at night, neon sign closeup, cinematic frame"
}
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',
    prompt: 'Cyberpunk city at night, neon sign closeup, cinematic frame'
  })
};

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',
    'prompt' => 'Cyberpunk city at night, neon sign closeup, cinematic frame'
  ]),
  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\",\n  \"prompt\": \"Cyberpunk city at night, neon sign closeup, cinematic frame\"\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\",\n  \"prompt\": \"Cyberpunk city at night, neon sign closeup, cinematic frame\"\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\",\n  \"prompt\": \"Cyberpunk city at night, neon sign closeup, cinematic frame\"\n}"

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

200

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

🖥️ Browser Playground limitation (important)

This endpoint returns a raw base64 string (typically several MB) in the response. Due to browser rendering limits, the Playground on the right may show 请求时发生错误: unable to complete request after the response arrives — the request actually succeeded; the browser just can’t render such a long base64 string.

Recommended workflow (beginner-friendly):

• Copy the Python / Node.js / cURL sample below and run it locally. The code automatically base64.b64decodes the response and writes the image to a file.
• If you must use the in-browser Playground, set size to the smallest tier (e.g. 1024x1024) and quality to low to shrink the response.

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.

⚠️ 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

Param	Type	Required	Default	Description
model	string	Yes	—	Fixed: gpt-image-2
prompt	string	Yes	—	Prompt, supports both Chinese and English
size	string	No	auto	Output size — preset or constraint-satisfying custom
quality	string	No	auto	low / medium / high / auto
output_format	string	No	png	png / jpeg / webp
output_compression	int	No	—	0–100, only for jpeg / webp
background	string	No	auto	opaque / auto (not supported: transparent)
moderation	string	No	auto	auto / low (low-strength moderation)
n	int	No	1	Only 1 supported

Do not pass the legacy DALL·E values standard / hd for quality. Only the four official enum values low / medium / high / auto are accepted. The legacy values behave inconsistently across backend channels: sometimes they fail immediately with a 400 (invalid_value), and sometimes they are silently ignored and the request runs at auto (unpredictable cost). Always pass one of the four official values explicitly.

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": 17,
        "input_tokens_details": {
            "image_tokens": 0,
            "text_tokens": 17
        },
        "output_tokens": 196,
        "output_tokens_details": {
            "image_tokens": 196,
            "text_tokens": 0
        },
        "total_tokens": 213
    }
}

⚠️ 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

As of July 2026, gpt-image-2-all / gpt-image-2-vip also return raw base64, but their earlier versions included the prefix — when sharing code across models, always check startsWith('data:') first.

The usage field reflects actual billed tokens for this call. input_tokens_details / output_tokens_details break text and image tokens out separately (image_tokens is always 0 for plain text-to-image). For the full field reference and a self-service cost formula, see How to check the real token count for each call on the overview page.

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

200

application/json

Image generated successfully

created · integer

Unix timestamp

Example:

1776832476

data · object[]

Generation results (this model returns 1 image per call)

Show child attributes

usage · object

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

Show child attributes