Формат изображений OpenAI

Общие сведения

• Base URL: https://api.routeapi.ai
• Аутентификация: Authorization: Bearer $ROUTEAPI_KEY с API Key, начинающимся с sk- (создаётся на странице API-ключи). Управляющие ключи с префиксом rat_ не могут вызывать модели.
• Формат ошибок: {"error": {"message": "...", "type": "...", "code": "..."}}; значения кодов состояния описаны в разделе Частые ошибки.

RouteAPI предоставляет генерацию изображений через OpenAI-совместимые эндпоинты images. На этой странице описаны общая структура запроса и семейство OpenAI gpt-image — в продаже есть gpt-image-2. Запросы других поставщиков адаптируются к тем же эндпоинтам; их особенности описаны отдельно: Nano Banana для моделей изображений Gemini, Seedream для ByteDance.

Поддержку генерации изображений можно увидеть в списке моделей: в поле supported_endpoint_types такой модели присутствует image-generation. О том, как читать это поле, см. Модели.

Эндпоинты

POST /v1/images/generations
POST /v1/images/edits

Полные URL:

https://api.routeapi.ai/v1/images/generations
https://api.routeapi.ai/v1/images/edits

/v1/images/generations принимает тело JSON. /v1/images/edits принимает multipart/form-data — либо, на OpenAI-совместимых каналах, тело JSON со ссылками на изображения по URL или Base64 (см. Правки через JSON).

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

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

Поле	Тип	Обязательно	Описание
model	string	Да	ID модели из GET /v1/models, например gpt-image-2
prompt	string	Да	Текстовое описание изображения для генерации
n	integer	Нет	Количество изображений, до 128. Если не указано или равно 0, считается равным 1
size	string	Нет	Размер результата, например 1024x1024, 1024x1536, или ступень вроде 1K / 2K, в зависимости от модели. В теле JSON используйте разделитель x — полноширинный × отклоняется с 400
quality	string	Нет	Уровень качества, например standard, hd, high, medium, low или auto. Допустимые значения зависят от модели
response_format	string	Нет	url или b64_json. Передаётся в upstream; какое значение учитывает модель, определяет поставщик
style	string	Нет	Подсказка стиля (например, vivid или natural). Имеет смысл только для моделей, которые её принимают
user	string	Нет	Идентификатор конечного пользователя, передаваемый в upstream
watermark	boolean	Нет	Нужно ли наносить водяной знак на результат, для поставщиков, которые это поддерживают

Шлюз также понимает поля background, output_format, output_compression, input_fidelity, moderation и partial_images; при наличии они передаются в OpenAI-совместимые upstream. Неизвестные поля JSON отбрасываются, а не передаются, если канал не работает в режиме сквозной передачи тела запроса.

Note

Значения по умолчанию зависят от модели. Шлюз добавляет quality: "auto" для gpt-image-1 при JSON-генерации и не задаёт значение по умолчанию для gpt-image-2. Устаревшая dall-e-3 по умолчанию использует size: "1024x1024" и quality: "standard" и принимает только 1024x1024, 1024x1792 и 1792x1024.

prompt обязателен для модели в upstream, но RouteAPI не отклоняет его заранее: пустой prompt передаётся дальше, и поставщик сам решает, завершать ли запрос ошибкой.

n больше 128 отклоняется до передачи запроса.

Пример запроса

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A calico cat playing a piano on a small stage, soft studio lighting",
    "size": "1024x1024",
    "n": 1
  }'

Python (OpenAI SDK)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="A calico cat playing a piano on a small stage, soft studio lighting",
    size="1024x1024",
    n=1,
)

for item in result.data:
    print(item.url or item.b64_json[:40])

Ответ

OpenAI-совместимые каналы возвращают тело upstream как есть. В зависимости от модели data[] содержит b64_json, url или оба поля — читайте то, что присутствует.

{
  "created": 1740000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 4160,
    "total_tokens": 4172
  }
}

Поле	Описание
created	Unix-время генерации
data	Массив сгенерированных изображений, по одному элементу на изображение
data[].url	URL изображения, если upstream возвращает ссылки
data[].b64_json	Байты изображения в Base64, если upstream возвращает Base64
data[].revised_prompt	Переписанный prompt, если модель его возвращает
usage	Расход токенов, присутствует только если upstream его вернул

Используйте url / b64_json — то, что присутствует; не рассчитывайте на оба поля и считайте usage необязательным при разборе.

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

POST /v1/images/edits изменяет существующее изображение с помощью prompt и, необязательно, маски.

Поля multipart

Поле	Тип	Обязательно	Описание
model	string	Да	ID модели из GET /v1/models
image	file	Да	Исходное изображение. Чтобы передать несколько, повторите поле или используйте image[]
prompt	string	Да	Инструкция с описанием правки
mask	file	Нет	Маска, отмечающая область для правки. Семантику маски определяет модель upstream
n	integer	Нет	Количество результатов, до 128 (по умолчанию 1)
size	string	Нет	Размер результата, по тем же правилам, что и при генерации
quality	string	Нет	Уровень качества, поддерживаемый моделью
watermark	boolean	Нет	Нужно ли наносить водяной знак на результат

Остальные поля формы передаются без изменений в OpenAI-совместимые upstream, поэтому параметры вроде response_format или input_fidelity тоже проходят.

Пример multipart-запроса

curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F model="gpt-image-2" \
  -F prompt="Replace the background with a sunset beach" \
  -F image=@"cat.png" \
  -F size="1024x1024"

Python (OpenAI SDK)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

with open("cat.png", "rb") as image:
    result = client.images.edit(
        model="gpt-image-2",
        image=image,
        prompt="Replace the background with a sunset beach",
        size="1024x1024",
    )

print(result.data[0].b64_json[:40])

Правки через JSON

На OpenAI-совместимых каналах /v1/images/edits также принимает тело JSON. RouteAPI скачивает или декодирует каждую ссылку на изображение и заново собирает multipart-запрос в upstream — используйте этот способ, когда изображения уже находятся по URL или представлены строками Base64.

curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Repaint this photo as a watercolor illustration",
    "images": [
      { "image_url": "https://example.com/photo.png" }
    ],
    "size": "1024x1024"
  }'

Каждый элемент images может содержать image_url (или url) в виде ссылки http(s) или строки data:image/...;base64,.... mask использует ту же структуру. На этом пути массив images обязателен; отдельное поле image не читается. Другие семейства каналов могут по-прежнему ожидать настоящий multipart, поэтому проверьте целевую модель, прежде чем полагаться на JSON-правки.

Другие поставщики на тех же эндпоинтах

Эндпоинты и структура prompt / n / size общие, но каждый адаптер поставщика преобразует их по-своему.

Семейство поставщика	Страница
Модели изображений Google Gemini (gemini-*-image*)	Nano Banana
ByteDance Seedream (seedream-5.0-pro, seedream-5.0-lite)	Seedream

Тарификация

Модели gpt-image тарифицируются по токенам: сгенерированные изображения считаются выходными токенами по цене выхода, а prompt и изображения-референсы — входными токенами. Изображения большего размера и более высокого качества расходуют больше токенов. Полные правила см. в разделе Тарификация моделей, а применимый способ — на странице модели.

На моделях с оплатой за изображение и ступенями размера цена выбирается по количеству пикселей запрошенного size ещё до выбора канала; n оплачивается за каждое изображение, а пропущенный или нераспознанный size приводит к применению максимальной цены за единицу.

Ошибки и ограничения

Статус	Значение	Типичная причина
400	Некорректный запрос	Отсутствует model, n больше 128, неподдерживаемый size для модели, × в качестве разделителя размера в теле JSON
401	Ошибка аутентификации	API Key отсутствует, недействителен, просрочен или исчерпан
403	Исчерпан баланс или квота	insufficient_user_quota или pre_consume_token_quota_failed; пополните баланс или увеличьте квоту ключа
429	Превышен лимит запросов	Снизьте параллелизм
500	Ошибка преобразования или внутренняя ошибка	Запрос не удалось преобразовать для выбранного канала, или в правке не было пригодного изображения
501	api_not_implemented	Эндпоинт существует, но не поддерживается

POST /v1/images/variations не поддерживается и возвращает 501 с кодом api_not_implemented; используйте правку на основе prompt. Для /v1/images/edits нужно хотя бы одно изображение — распознаются имена полей формы image, image[] и в форме image[0].

Что дальше

• Nano Banana — модели изображений Gemini, включая нативный путь generateContent.
• Seedream — размеры, последовательная генерация и правки ByteDance Seedream.
• Модели — найдите модели изображений и подтвердите поддержку image-generation.
• Тарификация моделей — оплата по токенам и за изображение, ступени размера.
• Частые ошибки — общие коды состояния и формат тела ошибки.