Images API

Two endpoints: Generate (text → image) and Edit (image + text → image). Both responses follow the OpenAI standard shape data[0].b64_json.

Seedream and Qwen-Image do not support /v1/images/edits; for image-to-image they use the generations endpoint, but with different reference-image fields: Seedream uses image, Qwen uses input_images — don’t mix them up. When you need to control Gemini’s resolution (512 to 4K), use the Gemini native protocol. Parameter differences for each family are covered on its family page.

Quickstart

A minimal runnable request: generate one 1024×1024 image and save it as output.png.

import base64
from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_OFOX_API_KEY",
    base_url="https://api.ofox.io/v1",
    timeout=600,  # the images API is synchronous and can be slow
)
 
resp = client.images.generate(
    model="openai/gpt-image-2.5-flare",
    prompt="A red apple on a white table",
    size="1024x1024",
    quality="low",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

curl https://api.ofox.io/v1/images/generations \
  --max-time 600 \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2.5-flare",
    "prompt": "A red apple on a white table",
    "size": "1024x1024",
    "quality": "low"
  }' | jq -r '.data[0].b64_json' | base64 --decode > output.png

All families are called the same way — only model changes. Accepted values and family-specific parameters differ; see each parameter below.

Generate images

POST https://api.ofox.io/v1/images/generations

Request parameters

Values and defaults below apply to the GPT Image family (gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2). Where other families differ, it says so. Measured details: GPT Image family.

Response

{
  "created": 1777385517,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "index": 0 }
  ],
  "model": "openai/gpt-image-2.5-flare",
  "size": "1024x1024",
  "quality": "low",
  "usage": {
    "input_tokens": 13,
    "input_tokens_details": { "text_tokens": 13 },
    "output_tokens": 196,
    "output_tokens_details": { "image_tokens": 196 },
    "total_tokens": 209
  }
}

Edit images

POST https://api.ofox.io/v1/images/edits

Request parameters

Sent as multipart/form-data form fields, with an uploaded image file. Values and defaults again apply to the GPT Image family.

Response

Same shape as generations; usage adds input tokens for the reference images:

{
  "created": 1777385669,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "index": 0 }
  ],
  "model": "openai/gpt-image-2",
  "size": "auto",
  "quality": "low",
  "usage": {
    "input_tokens": 1041,
    "input_tokens_details": { "image_tokens": 1024, "text_tokens": 17 },
    "num_input_images": 1,
    "output_tokens": 358,
    "total_tokens": 1399
  }
}

Other fields are the same as the generations response.

Call

import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.io/v1", timeout=600)
 
with open("apple.png", "rb") as f:
    resp = client.images.edit(
        model="openai/gpt-image-2",
        image=f,
        prompt="Make the apple green, keep everything else the same",
        size="auto",
        quality="low",
    )
 
with open("apple_edited.png", "wb") as out:
    out.write(base64.b64decode(resp.data[0].b64_json))

import OpenAI, { toFile } from 'openai'
import fs from 'node:fs'
 
const client = new OpenAI({
  apiKey: 'YOUR_OFOX_API_KEY',
  baseURL: 'https://api.ofox.io/v1',
  timeout: 600_000, // milliseconds
})
 
const resp = await client.images.edit({
  model: 'openai/gpt-image-2',
  image: await toFile(fs.createReadStream('apple.png'), 'apple.png'),
  prompt: 'Make the apple green, keep everything else the same',
  size: 'auto',
  quality: 'low',
})
 
fs.writeFileSync('apple_edited.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

curl -X POST 'https://api.ofox.io/v1/images/edits' \
  --max-time 600 \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -F 'model="openai/gpt-image-2"' \
  -F 'prompt="Make the apple green, keep everything else the same"' \
  -F 'image=@/path/to/apple.png' \
  -F 'size="auto"' \
  -F 'quality="low"'

The image field takes a local file path (with the @ prefix in cURL), not a URL.

Measured before / after:

Original	Edited

Errors

Errors come back with an HTTP error status and this body (measured):

{
  "error": {
    "code": null,
    "message": "The model 'gpt-image-2' does not support quality 'xhigh'.",
    "param": null,
    "request_id": "fbe4f24c-779d-41a0-8b3a-c62886cdd1ae",
    "type": "image_generation_user_error"
  }
}

code can be null. Branch on the HTTP status and message.

When contacting support, include the request_id and the error details (HTTP status and error.message) from the response. We recommend logging them.

Advanced: pinning a provider

Optional and usually unnecessary. All three GPT Image models (gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2) are served by both azure_foundry and openai, for generations and edits alike. Without a pin, the gateway routes automatically.

Select a provider when you have content moderation requirements. Requests then go only to that provider; if it is unavailable, they will not fall back to another provider automatically.

Naming a provider that does not serve the model returns 400 provider_type_unavailable.

Text to image /v1/images/generations

JSON body, so either the body field extra_body.provider.type or the header X-OfoxAI-Provider-Type works.

resp = client.images.generate(
    model="openai/gpt-image-2",
    prompt="A simple red apple on a white table",
    size="1024x1024",
    extra_body={"extra_body": {"provider": {"type": "openai"}}},
)

const resp = await client.images.generate({
  model: 'openai/gpt-image-2',
  prompt: 'A simple red apple on a white table',
  size: '1024x1024',
  extra_body: { provider: { type: 'openai' } },
})

curl https://api.ofox.io/v1/images/generations \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "...",
    "n": 1,
    "size": "1024x1024",
    "extra_body": { "provider": { "type": "openai" } }
  }'

Image to image /v1/images/edits

A multipart upload has no JSON body to nest extra_body in, so only the header works.

curl https://api.ofox.io/v1/images/edits \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "X-OfoxAI-Provider-Type: openai" \
  -F "model=openai/gpt-image-2" \
  -F "prompt=..." \
  -F "image=@input.png"

With the SDKs: in Python pass extra_headers={"X-OfoxAI-Provider-Type": "openai"}; in TypeScript pass { headers: { 'X-OfoxAI-Provider-Type': 'openai' } } as the second argument.

Full reference: API · Provider routing.

Official docs & further reading

The official docs describe calling OpenAI directly. Where they differ from OfoxAI’s measured behavior, the measured behavior on this site takes precedence.

OpenAI

• Image generation guide · Generate images 
• Image generation guide · Edit images 
• Image generation guide · Edit an image using a mask 
• Image generation guide · Size and quality options 
• Image generation guide · Calculating costs 
• Images API reference 

OfoxAI family pages

• GPT Image family overview: choosing a model, size, quality, latency, errors
• Text to image
• Image editing & multi-image
• Inpainting
• Nano Banana family (Gemini Image) and troubleshooting errors
• Seedream family
• Qwen-Image family
• MAI Image family