Images API

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

Что нужно сделать	Эндпоинт	Поддерживаемые модели
Сгенерировать изображение по тексту	`POST /v1/images/generations`	`openai/gpt-image-2`, `google/gemini-3.1-flash-image`, `bailian/qwen-image-3.0-pro`
Загрузить изображение и изменить его по инструкции	`POST /v1/images/edits`	Только OpenAI / Azure: `openai/gpt-image-2`, `openai/gpt-image-1.5`

Два исключения для режима «изображение → изображение»: серия Qwen работает через поле input_images эндпоинта generations, а не edits; серия Gemini не умеет редактировать ни на одном из эндпоинтов этой страницы — используйте нативный протокол Gemini.

Закрепление провайдера

provider.type закрепляет запрос за одним провайдером. Это имеет смысл только для моделей, которые обслуживает более одного — сегодня это openai/gpt-image-2 (azure_foundry и openai). Указание провайдера, не обслуживающего модель, возвращает 400 provider_type_unavailable.

Провайдер	Описание	Модерация контента
`azure_foundry`	Размещено в Microsoft Azure	Строже
`openai`	Собственный API OpenAI	Мягче

Два провайдера openai/gpt-image-2 модерируют по-разному: azure_foundry строже, openai мягче. Если промпт раз за разом отклоняется, укажите provider.type: "openai" явно — иначе взвешенное распределение может отправить запрос в azure_foundry.

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

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

/v1/images/generations принимает JSON-тело, поэтому работают и поле в теле, и заголовок.

Python

gen_pinned.py


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"}}},
)

TypeScript

gen_pinned.ts


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

Terminal


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

В официальных SDK OpenAI extra_body должен присутствовать в теле запроса как буквальный ключ. TypeScript SDK отправляет его ровно так, как он записан в объекте параметров. Аргумент extra_body= в Python SDK сливает своё содержимое с верхним уровнем тела, поэтому ключ нужно вложить на уровень глубже либо передать через заголовок запроса.

Редактирование изображения — `/v1/images/edits`

/v1/images/edits — это multipart-загрузка: JSON-тела, в которое можно вложить extra_body, здесь нет, поэтому работает только заголовок. Переданный как поле формы extra_body игнорируется, и запрос выполняется без ограничения.

Terminal


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"

В /v1/images/edits переданный полем формы extra_body молча игнорируется — изображение создаётся без ограничения. Используйте X-OfoxAI-Provider-Type.

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


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

Параметры

Параметр	Тип	Обязателен	Описание
`model`	string	✅	`openai/gpt-image-2`, `google/gemini-3.1-flash-image`, `bailian/qwen-image-3.0-pro`
`prompt`	string	✅	Описание на естественном языке
`quality`	string	✅	`auto` / `low` / `medium` / `high` / `standard` / `hd`
`n`	number	—	1–10, по умолчанию 1. Не поддерживается моделями Gemini
`size`	string	—	`auto` / `1024x1024` / `1536x1024` / `1024x1536` / `256x256` / `512x512` / `1792x1024` / `1024x1792`
`input_images`	string[]	—	Массив референсных изображений (URL или base64), от 1 до 3, поддерживается моделями изображений Qwen; при срабатывании ответ содержит `usage.num_input_images`
`output_format`	string	—	`png` / `jpeg` / `webp`
`background`	string	—	`transparent` / `opaque` / `auto`
`stream`	boolean	—	По умолчанию `false`
`extra_body.provider.type`	string	—	Закрепляет запрос за провайдером. Имеет смысл только для моделей, которые обслуживает несколько провайдеров (на этом эндпоинте сейчас `openai/gpt-image-2`); заголовок `X-OfoxAI-Provider-Type` равнозначен

Ответ


{
  "created": 1777385517,
  "data": [
    { "b64_json": "<Base64 изображения>", "index": 0 }
  ],
  "model": "openai/gpt-image-2",
  "size": "1024x1024",
  "quality": "low",
  "usage": {
    "input_tokens": 14,
    "input_tokens_details": { "text_tokens": 14 },
    "output_tokens": 208,
    "total_tokens": 222
  }
}

Изображение находится в data[0].b64_json — декодируйте Base64 и сохраняйте локально.

Серия OpenAI (gpt-image-2)

Python

gen.py


import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.io/v1")
 
resp = client.images.generate(
    model="openai/gpt-image-2",
    prompt="A simple red apple on a white table",
    size="1024x1024",
    quality="low",
    output_format="png",
    # Необязательно: закрепить провайдера. Без этого поля платформа маршрутизирует сама
    # extra_body={"extra_body": {"provider": {"type": "openai"}}},
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

TypeScript

gen.ts


import OpenAI from 'openai'
import fs from 'node:fs'
 
const client = new OpenAI({ apiKey: 'YOUR_OFOX_API_KEY', baseURL: 'https://api.ofox.io/v1' })
 
const resp = await client.images.generate({
  model: 'openai/gpt-image-2',
  prompt: 'A simple red apple on a white table',
  size: '1024x1024',
  quality: 'low',
  output_format: 'png',
  // Необязательно: закрепить провайдера. Без этого поля платформа маршрутизирует сама
  // extra_body: { provider: { type: 'openai' } },
})
 
fs.writeFileSync('output.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

cURL

Terminal


# Необязательно: закрепить провайдера. Без этого поля платформа маршрутизирует сама
# "extra_body": { "provider": { "type": "openai" } }
curl -X POST 'https://api.ofox.io/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A simple red apple on a white table",
    "size": "1024x1024",
    "quality": "low",
    "output_format": "png"
  }'

Реальный результат:

Красное яблоко, сгенерированное gpt-image-2

Серия Gemini (gemini-3.1-flash-image)

Тот же эндпоинт принимает и модели генерации изображений Gemini. Не передавайте параметр n — шлюз ошибочно мапит n в поле numberOfImages и возвращает 400. Каждый вызов всегда генерирует одно изображение.

Python

gen_gemini.py


import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.io/v1")
 
resp = client.images.generate(
    model="google/gemini-3.1-flash-image",
    prompt="A simple red apple on a white table, photorealistic",
    size="1024x1024",
    quality="low",
    output_format="png",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

TypeScript

gen_gemini.ts


import OpenAI from 'openai'
import fs from 'node:fs'
 
const client = new OpenAI({ apiKey: 'YOUR_OFOX_API_KEY', baseURL: 'https://api.ofox.io/v1' })
 
const resp = await client.images.generate({
  model: 'google/gemini-3.1-flash-image',
  prompt: 'A simple red apple on a white table, photorealistic',
  size: '1024x1024',
  quality: 'low',
  output_format: 'png',
})
 
fs.writeFileSync('output.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

cURL

Terminal


curl -X POST 'https://api.ofox.io/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "google/gemini-3.1-flash-image",
    "prompt": "A simple red apple on a white table, photorealistic",
    "size": "1024x1024",
    "quality": "low"
  }'

Реальный результат:

Красное яблоко, сгенерированное Gemini

Серия Qwen (qwen-image-3.0-pro)

Модели изображений Qwen, например bailian/qwen-image-3.0-pro, принимают референсные изображения для режима «изображение → изображение» и редактирования прямо на этом эндпоинте (от 1 до 3 изображений) — через поле input_images (элемент — URL изображения или строка base64):

Terminal


curl -X POST 'https://api.ofox.io/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "bailian/qwen-image-3.0-pro",
    "prompt": "Сделай яблоко синим, остальное оставь без изменений",
    "size": "1024x1024",
    "input_images": ["https://example.com/ref-apple.png"]
  }'

Если референсные изображения приняты, в ответе внутри usage появляется num_input_images (число входных изображений) — по нему можно программно убедиться, что модель их прочитала.

Поле должно называться именно input_images. Другие варианты — image_urls, image, images — молча игнорируются, и запрос вырождается в обычную генерацию по тексту (HTTP по-прежнему 200).

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


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

Формат multipart/form-data — необходимо загрузить файл изображения.

Этот эндпоинт поддерживает только модели OpenAI / Azure OpenAI. Вызов с google/gemini-3.1-flash-image вернёт Image editing is not supported for model — переходите на редактирование изображений через нативный протокол Gemini.

Параметры

Параметр	Тип	Обязателен	Описание
`model`	string	✅	Рекомендуется `openai/gpt-image-2`
`image`	file	✅	Файл PNG / JPEG
`prompt`	string	✅	Инструкция по редактированию
`quality`	string	✅	`low` / `medium` / `high`
`n`	number	—	По умолчанию 1
`size`	string	—	`auto` соответствует размеру оригинала
`X-OfoxAI-Provider-Type`	заголовок	—	Закрепляет запрос за провайдером. Этот эндпоинт — multipart-загрузка, поэтому работает только заголовок: поле формы `extra_body` молча игнорируется

Ответ

Совпадает с ответом генерации:


{
  "created": 1777385669,
  "data": [
    { "b64_json": "<Base64 отредактированного изображения>", "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
  }
}

usage.input_tokens_details.image_tokens — токены, потраченные на входное изображение, num_input_images — количество входных изображений.

Поддерживаемые модели и цены см. в Каталоге моделей .

Вызов

Python

edit.py


import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.io/v1")
 
with open("apple.png", "rb") as f:
    resp = client.images.edit(
        model="openai/gpt-image-2",
        image=f,
        prompt="Сделай яблоко зелёным, остальное оставь без изменений",
        size="auto",
        quality="low",
        # Необязательно: закрепить провайдера. Этот эндпоинт — multipart, работает только заголовок
        # extra_headers={"X-OfoxAI-Provider-Type": "openai"},
    )
 
with open("apple_edited.png", "wb") as out:
    out.write(base64.b64decode(resp.data[0].b64_json))

TypeScript

edit.ts


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' })
 
// Необязательно: закрепить провайдера. Этот эндпоинт — multipart, работает только заголовок
// передайте { headers: { 'X-OfoxAI-Provider-Type': 'openai' } } вторым аргументом
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

Terminal


# Необязательно: закрепить провайдера. Этот эндпоинт — multipart, работает только заголовок
# -H 'X-OfoxAI-Provider-Type: openai' \
curl -X POST 'https://api.ofox.io/v1/images/edits' \
  -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.

Сравнение результатов:

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

Images API

Закрепление провайдера

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

Python

TypeScript

cURL

Редактирование изображения — /v1/images/edits

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

Параметры

Ответ

Серия OpenAI (gpt-image-2)

Python

TypeScript

cURL

Серия Gemini (gemini-3.1-flash-image)

Python

TypeScript

cURL

Серия Qwen (qwen-image-3.0-pro)

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

Параметры

Ответ

Вызов

Python

TypeScript

cURL

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

Редактирование изображения — `/v1/images/edits`