Image Generation API

OpenAI-compatible image generation endpoint, supporting image models like gpt-image-2.

Request

POST /v1/images/generations

Headers

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

You can also use the x-api-key header (Anthropic SDK style):

x-api-key: pk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

Request Body

Supported Sizes

Tokensmart does not restrict image sizes — any size the image model supports will work. We do not maintain a static whitelist.

Format constraints (lightweight Tokensmart-side validation):

• Must be a string, ≤ 16 characters
• Must be auto or WIDTHxHEIGHT format (digits only, lowercase x separator, e.g. 1024x1024, 2048x2048)
• The following are rejected with 400 invalid_request: keyword strings (big, large), values with spaces (1024 x 1024), non-string values (numbers, objects), oversized strings

Verified working sizes (against gpt-image-2, as of 2026-04-25):

Unsupported sizes (e.g. 4096x4096): the request returns 502 upstream_error and the pre-deduction is automatically refunded — no charge to your balance.

Request Example

{
  "model": "gpt-image-2",
  "prompt": "a cute orange cat wearing a wizard hat, sitting on a rooftop under moonlight, watercolor style",
  "n": 1,
  "size": "1024x1024",
  "quality": "auto"
}

Response

{
  "created": 1776864985,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ]
}

Each item in the data array contains:

Billing

Image models use per-call billing, not token-based:

• Fixed price per image — see Pricing
• Pre-deduction freezes balance for the requested n, settlement charges for actually returned images
• If fewer images than requested are returned, the difference is automatically refunded

Python Example

from openai import OpenAI
import base64

client = OpenAI(
    api_key="pk_live_xxxxxxxxxxxxxxxx",
    base_url="https://api.tokensmart.ai/v1",
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="a cute cat wearing a wizard hat on a rooftop under moonlight, watercolor style",
    n=1,
    size="1024x1024",
)

# Save image
image_data = base64.b64decode(result.data[0].b64_json)
with open("cat.png", "wb") as f:
    f.write(image_data)

cURL Example

curl https://api.tokensmart.ai/v1/images/generations \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a cute cat wearing a wizard hat on a rooftop under moonlight, watercolor style",
    "n": 1,
    "size": "1024x1024"
  }'

Node.js Example

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  apiKey: "pk_live_xxxxxxxxxxxxxxxx",
  baseURL: "https://api.tokensmart.ai/v1",
});

const result = await client.images.generate({
  model: "gpt-image-2",
  prompt: "a cute cat wearing a wizard hat",
  n: 1,
  size: "1024x1024",
});

// Save image
const imageData = Buffer.from(result.data[0].b64_json, "base64");
fs.writeFileSync("cat.png", imageData);

Error Codes

Important Notes

• Image generation typically takes 30-90 seconds — set a long enough timeout
• Base64 image data is large (1-5 MB per image) — watch client memory
• gpt-image-2 currently supports max 1 image per request
• For non-image models (gpt-5.5, Claude, etc.), use /v1/chat/completions or /v1/messages

Related Endpoints

• Image-to-image editing (edit an existing image): see Image Edits API
• Multi-image compose (blend several reference images): see Image Compose API
• Upload external images (prerequisite for image-to-image): see File Upload API