GPT-Image-2 API Guide

GPT-Image-2 — OpenAI Image Generation API

Access OpenAI's latest image generation model through the TokenHub unified API. Fully OpenAI-compatible, with synchronous response (no polling required), multiple sizes up to 4K, quality levels, and PNG/JPEG/WebP output formats. Supports both text-to-image (t2i) and image-to-image editing (i2i, multi-image composition & inpainting). This guide walks you through the complete integration.

Text → ImageImage → Image (i2i)OpenAI-CompatibleSynchronousUp to 4KToken-based

1Get Your API Key

Visit tokenhub.store to create an account (GitHub / Google sign-in supported)
Go to Dashboard → API Keys, click "Create New Key"
Go to Dashboard → Billing to add credits (1 Credit = $1 USD)
Copy your API Key (format: th-xxxxxxxxxxxx...)

⚠️ The API Key is only shown once upon creation. Save it securely. If lost, you'll need to create a new one.

2API Overview

Base URL

https://tokenhub.store/api/v1

Authentication

All requests require an API Key in the header:

Header

Authorization: Bearer th-your-api-key

Endpoints (Synchronous, OpenAI-compatible)

POST

/images/generations

Text-to-image. Generate images from a text prompt.

POST

/images/edits

Image-to-image editing. Supports single-image edits, multi-image composition, and optional inpainting with a mask.

3Pricing

Tier	Price	Resolution range
1K	$0.125 / image	Longest side ≤ 1536 px (e.g. 1024×1024, 1024×1536)
2K	$0.250 / image	Longest side ≤ 2048 px (e.g. 2048×2048)
4K	$0.500 / image	Longest side > 2048 px (e.g. 4096×4096)

Flat per-image pricing based on output resolution tier (determined by the longest side of size). n images = unit price × n. Failed calls are not charged.

Tier mapping by longest side: ≤ 1536 px → 1K ($0.125), ≤ 2048 px → 2K ($0.250), > 2048 px → 4K ($0.500). Examples: 1024×1024 and 1024×1536 are both 1K; 2048×2048 is 2K; 4096×4096 is 4K.

4Request Parameters

Parameter	Type	Required	Default	Description
model	string	Required	—	Model ID. Use "openai/gpt-image-2" (or short form "gpt-image-2").
prompt	string	Required	—	Text prompt describing the image to generate.
n	integer	Optional	1	Number of images to generate (1–10).
size	string	Optional	1024x1024	Output dimensions. Options: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 2048x1152, 3840x2160, 2160x3840, auto.
quality	string	Optional	auto	Generation quality. Options: auto, low, medium, high. Higher quality consumes more tokens.
format	string	Optional	png	Output image format. Options: png, jpeg, webp.

Additional fields for /images/edits (i2i)

Parameter	Type	Required	Default	Description
image	file / string \| array	Required	—	Input image(s) to edit. Accepts file(s) via multipart, or URL / base64 data URI in JSON. Provide multiple to compose them into one output.
mask	file / string	Optional	—	Optional inpainting mask. Transparent areas will be regenerated; opaque areas are preserved.
input_fidelity	string	Optional	low	How closely to preserve the input. Options: low, high. Use high to keep identity/layout; use low for bolder transformations.
output_format	string	Optional	png	Alias of 'format' for the edit endpoint. Options: png, jpeg, webp.
output_compression	integer	Optional	100	Compression level 0–100 (only for jpeg / webp).

5Complete curl Example

bash

curl -X POST https://tokenhub.store/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A serene Japanese garden at sunset, koi pond reflections, cherry blossoms, soft cinematic lighting, ultra-detailed"
  }'

Response:

json

{
  "created": 1740000000,
  "data": [
    {
      "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

6Python Full Example

python

# pip install openai
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://tokenhub.store/api/v1",
)

result = client.images.generate(
    model="openai/gpt-image-2",
    prompt="A majestic dragon flying over snowy mountains at dawn, epic fantasy art, ultra-detailed",
    n=1,
    size="1536x1024",
    quality="high",
)

image_url = result.data[0].url
print("Image URL:", image_url[:80], "...")

7JavaScript / Node.js Full Example

javascript

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://tokenhub.store/api/v1",
});

const result = await client.images.generate({
  model: "openai/gpt-image-2",
  prompt: "A majestic dragon flying over snowy mountains at dawn, epic fantasy art, ultra-detailed",
  n: 1,
  size: "1536x1024",
  quality: "high",
});

console.log("Image URL:", result.data[0].url.slice(0, 80), "...");

8Usage Tips

English prompts usually yield the best results; Chinese is also supported.
Response data[].url may be a plain https URL or a data URI (base64). Handle both cases when saving to disk.
To reduce cost, use low/medium quality for drafts and only use high/4K sizes for final output.
The endpoint is synchronous — no task id, no polling. A request usually completes in 5–30 seconds depending on size and quality.
Set HTTP timeout to ≥ 120s on the client side to avoid premature disconnection on large images.

9FAQ

Ready to Start?

Get API Key Top Up Credits