Images API

Два эндпоинта: генерация (текст → изображение) и редактирование (изображение + текст → изображение). Ответ в обоих случаях имеет стандартную структуру OpenAI — data[0].b64_json.

Seedream и Qwen-Image не поддерживают /v1/images/edits: режим «изображение → изображение» работает через эндпоинт generations, но поля для референсных изображений у них разные — Seedream использует image, Qwen — input_images; не перепутайте их. Если для Gemini нужно управлять разрешением (от 512 до 4K), используйте нативный протокол Gemini. Различия в параметрах описаны на странице каждого семейства.

Быстрый старт

Минимальный рабочий запрос: сгенерировать одно изображение 1024×1024, декодировать его и сохранить как 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,  # Images API отвечает синхронно и может работать долго
)
 
resp = client.images.generate(
    model="openai/gpt-image-2.5-flare",
    prompt="Красное яблоко на белом столе",
    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": "Красное яблоко на белом столе",
    "size": "1024x1024",
    "quality": "low"
  }' | jq -r '.data[0].b64_json' | base64 --decode > output.png

Все семейства вызываются одинаково — меняется только model. Допустимые значения и параметры, специфичные для семейства, различаются; см. описание каждого параметра ниже.

Генерация изображений

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

Параметры запроса

Значения и значения по умолчанию ниже относятся к семейству GPT Image (gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2). Отличия других семейств указаны отдельно. Подробности замеров: семейство GPT Image.

Ответ

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

Редактирование изображений

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

Параметры запроса

Передаются как поля формы multipart/form-data вместе с загружаемым файлом изображения. Значения и значения по умолчанию также относятся к семейству GPT Image.

Ответ

Структура та же, что при генерации; в usage добавляются входные токены референсных изображений:

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

Остальные поля такие же, как в ответе генерации.

Вызов

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="Сделай яблоко зелёным, остальное оставь без изменений",
        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, // миллисекунды
})
 
const resp = await client.images.edit({
  model: 'openai/gpt-image-2',
  image: await toFile(fs.createReadStream('apple.png'), 'apple.png'),
  prompt: 'Сделай яблоко зелёным, остальное оставь без изменений',
  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="Сделай яблоко зелёным, остальное оставь без изменений"' \
  -F 'image=@/path/to/apple.png' \
  -F 'size="auto"' \
  -F 'quality="low"'

В поле image передавайте локальный путь к файлу (в cURL — с префиксом @), а не URL.

Сравнение по замерам:

Оригинал	После редактирования

Ошибки

При ошибке возвращается HTTP-статус ошибки и следующее тело (по замерам):

{
  "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 может быть null. Ориентируйтесь на HTTP-статус и message.

Обращаясь в поддержку, приложите request_id и сведения об ошибке (HTTP-статус и error.message) из ответа. Рекомендуем записывать их в свои логи.

Дополнительно: закрепление провайдера

Необязательно и обычно не нужно. Все три модели GPT Image (gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2) обслуживаются провайдерами azure_foundry и openai — как для генерации, так и для редактирования. Без закрепления шлюз маршрутизирует запросы автоматически.

Выбирайте провайдера, если у вас есть требования к модерации контента. В этом случае запросы отправляются только этому провайдеру; если он недоступен, автоматического переключения на другого провайдера не происходит.

Указание провайдера, который не обслуживает модель, возвращает 400 provider_type_unavailable.

Текст в изображение — /v1/images/generations

Тело запроса в формате JSON, поэтому работают оба способа: поле тела extra_body.provider.type и заголовок X-OfoxAI-Provider-Type.

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

Изображение в изображение — /v1/images/edits

У multipart-загрузки нет JSON-тела, в которое можно вложить extra_body, поэтому здесь работает только заголовок.

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"

В SDK: в Python передайте extra_headers={"X-OfoxAI-Provider-Type": "openai"}; в TypeScript передайте { headers: { 'X-OfoxAI-Provider-Type': 'openai' } } вторым аргументом.

Полный справочник: API · Маршрутизация провайдеров.

Официальная документация и дополнительные материалы

Официальная документация описывает поведение при прямом обращении к OpenAI. Если она расходится с замерами OfoxAI, приоритет имеют замеры на этом сайте.

Официальная документация OpenAI

• Руководство по генерации изображений · Генерация изображений 
• Руководство по генерации изображений · Редактирование изображений 
• Руководство по генерации изображений · Редактирование изображения с маской 
• Руководство по генерации изображений · Параметры размера и качества 
• Руководство по генерации изображений · Расчёт стоимости 
• Справочник Images API 

Страницы семейств OfoxAI

• Обзор семейства GPT Image: выбор модели, размер, качество, задержка, ошибки
• Текст в изображение
• Редактирование и объединение изображений
• Инпейнтинг
• Семейство Nano Banana (Gemini Image) и устранение ошибок
• Семейство Seedream
• Семейство Qwen-Image
• Семейство MAI Image