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

Генерируйте изображения с помощью AI-моделей через RouterAI API.

RouterAI предоставляет выделенный эндпоинт POST /api/v1/images для синхронной генерации изображений. Запрос принимает текстовый промпт и сразу возвращает готовые изображения в формате base64. Эндпоинт поддерживают модели, у которых есть "image" в списке output_modalities (например, openai/gpt-image-2, black-forest-labs/flux.2-pro, bytedance-seed/seedream-4.5).

Диалоговые модели, которые умеют возвращать картинки прямо в переписке (например, google/gemini-2.5-flash-image), работают через /api/v1/chat/completions — см. раздел «Диалоговые модели генерации изображений» ниже.

Поиск моделей

На странице моделей

Откройте страницу моделей и отфильтруйте по выходным модальностям — ищите модели с "image" в исходящих данных. На странице каждой модели в блоке Эндпоинт указано, какой именно эндпоинт она использует, а в блоке Параметры — поддерживаемые параметры.

Через каталог API

Получить список моделей программно можно запросом к GET /api/v1/models. Модели генерации изображений содержат "image" в architecture.output_modalities.

В чате

В чате выберите модель генерации изображений — появится панель «Генерация изображений» с настройками (соотношение сторон, размер, качество и т.д.).

Использование API

Базовая генерация

Отправьте POST /api/v1/images с обязательными полями model и prompt:

curl https://routerai.ru/api/v1/images \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "Рыжий кот в скафандре на фоне Земли, цифровая иллюстрация",
    "n": 1
  }'

Пример на Python:

import requests
import base64

response = requests.post(
    "https://routerai.ru/api/v1/images",
    headers={
        "Authorization": "Bearer $ROUTERAI_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/gpt-image-2",
        "prompt": "Рыжий кот в скафандре на фоне Земли, цифровая иллюстрация",
        "n": 1,
    },
)

result = response.json()
for i, image in enumerate(result.get("data", [])):
    with open(f"image_{i}.png", "wb") as f:
        f.write(base64.b64decode(image["b64_json"]))
    print(f"Сохранено: image_{i}.png")

print("Стоимость (₽):", result.get("usage", {}).get("cost"))

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

Параметр	Тип	Описание
`model`	string	Обязательно. Идентификатор модели (например, `openai/gpt-image-2`).
`prompt`	string	Обязательно для генерации с нуля. Текстовое описание желаемого изображения. Можно опустить при наличии `input_references` (правка/вариации).
`n`	integer	Количество изображений за запрос. Максимум зависит от модели.
`aspect_ratio`	string	Соотношение сторон (например, `1:1`, `16:9`, `9:16`).
`resolution`	string	Тир разрешения: `512`, `1K`, `2K`, `4K`.
`size`	string	Точный размер в пикселях (например, `1024x1024`).
`quality`	string	Качество: `auto`, `low`, `medium`, `high`; у `openai/gpt-image-2.5-*` также `xhigh` и `max`.
`background`	string	Фон: `auto`, `transparent`, `opaque`.
`output_format`	string	Формат вывода: `png`, `jpeg`, `webp`; у `openai/gpt-image-2.6-*` также `gif` — анимация, см. «Анимация (GIF)».
`output_compression`	integer	Степень сжатия `0–100` для `jpeg`/`webp`.
`frame_count`	integer	Число кадров GIF, `2–16` (по умолчанию 9). Только с `output_format: "gif"`.
`frame_duration_ms`	integer	Длительность кадра GIF в миллисекундах, `20–2000` (по умолчанию 200). Только с `output_format: "gif"`.
`seed`	integer	Сид для воспроизводимости результата.
`input_references`	array	Исходные изображения для image-to-image (правка/вариации).
`mask`	string \| object	Маска области правки, принимают модели `openai/gpt-image-*`. Точного inpaint не даёт — см. «Правка по маске».
`stream`	boolean	Потоковая отдача превью через SSE.

Набор поддерживаемых параметров зависит от модели. Неподдерживаемые значения модель игнорирует или нормализует. Точный список см. в блоке Параметры на странице модели.

Конфигурация изображения

Скомбинируйте параметры под нужный результат:

curl https://routerai.ru/api/v1/images \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d '{
    "model": "bytedance-seed/seedream-4.5",
    "prompt": "Минималистичный логотип кофейни, плоский дизайн",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "quality": "high",
    "output_format": "png",
    "background": "transparent"
  }'

Соотношение сторон (aspect_ratio). Распространённые значения — 1:1, 4:3, 3:4, 16:9, 9:16, 21:9. Допустимый набор зависит от модели и указан в таблице параметров на её странице. У google/gemini-3.1-flash-image, google/gemini-3.1-flash-image-preview и google/gemini-3.1-flash-lite-image дополнительно доступны вытянутые форматы 1:4, 1:8, 4:1, 8:1 (баннеры, ленты). Если модель Gemini не поддерживает запрошенное соотношение, оно приводится к ближайшему из её списка.

У моделей openai/gpt-image-* соотношение переводится в размер size:

openai/gpt-image-2.5-* — точный размер, который зависит ещё и от resolution (по умолчанию 1K):

`aspect_ratio`	`1K`	`2K`	`4K`
`1:1`	1024×1024	2048×2048	2880×2880
`3:2` / `2:3`	1536×1024	3072×2048	3504×2336
`4:3` / `3:4`	1536×1152	3072×2304	3264×2448
`16:9` / `9:16`	1536×864	3072×1728	3840×2160
`21:9`	1568×672	3136×1344	3808×1632

Для вертикальных форматов стороны меняются местами. 4K упирается в предел модели: сторона не больше 3840 и не больше 8,3 Мп, поэтому квадрат — 2880×2880. Нужен другой размер — передайте size в формате ШИРИНАxВЫСОТА: стороны кратны 16, соотношение от 1:3 до 3:1, сторона не больше 3840.

openai/gpt-image-1, gpt-image-1-mini, gpt-image-2 — только 1:1 (1024×1024), 3:2 (1536×1024) и 2:3 (1024×1536).

Разрешение (resolution). Тиры качества: 512, 1K, 2K, 4K. Набор зависит от модели: тир 512 есть у google/gemini-3.1-flash-image и -preview, google/gemini-3.1-flash-lite-image работает только в 1K. У openai/gpt-image-2.5-* тиры 1K, 2K и 4K задают размер картинки (таблица выше); 2K примерно вдвое дороже 1K, 4K — в 2,5–3,4 раза в зависимости от формата. Тир, которого у модели Gemini нет, приводится к ближайшему доступному.

Качество (quality). auto (по умолчанию у большинства), low, medium, high. У openai/gpt-image-2.5-* есть ещё два уровня выше high: xhigh и max. Качество влияет на цену, но не на размер картинки: у этих моделей счёт идёт за токены изображения, и картинка 1:1 в 1K в качестве high стоит около 1 800 токенов, в xhigh — около 3 100, в max — около 7 000. Размер задают aspect_ratio и resolution. Для quality: auto уровень выбирает сама модель, поэтому цена заранее не известна.

Формат и сжатие. output_format — png (по умолчанию), jpeg, webp. Для jpeg/webp можно задать output_compression (0–100).

Фон (background). transparent даёт прозрачный фон (для форматов с альфа-каналом, например png/webp).

Анимация (GIF)

openai/gpt-image-2.6-flare и openai/gpt-image-2.6-sunburst рисуют анимированный GIF: передайте output_format: "gif". Модель сама строит цикл кадров, в ответе — готовый GIF в b64_json с media_type: "image/gif".

curl https://routerai.ru/api/v1/images \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d '{
    "model": "openai/gpt-image-2.6-flare",
    "prompt": "Рыжий кот машет лапой, плоская иллюстрация, бесшовный цикл",
    "output_format": "gif",
    "frame_count": 9,
    "frame_duration_ms": 150,
    "aspect_ratio": "1:1",
    "quality": "medium"
  }' | jq -r '.data[0].b64_json' | base64 -d > cat.gif

Кадры и скорость. frame_count — от 2 до 16 (по умолчанию 9), frame_duration_ms — от 20 до 2000 мс (по умолчанию 200, точность 10 мс). Длительность цикла = кадры × длительность кадра.

Размер кадра. Все кадры рисуются на одном холсте, поэтому чем больше кадров, тем меньше кадр. aspect_ratio переводится в размер кадра:

`aspect_ratio`	до 9 кадров	10–16 кадров
`1:1`	768×768	512×512
`16:9` / `9:16`	1024×576 / 576×1024	768×432 / 432×768
без `aspect_ratio`	512×512	512×512

Можно передать свой size (размер кадра, стороны кратны 16), но 1024×1024 не поместится ни при каком числе кадров. resolution для GIF не применяется.

Оживить фото. С input_references модель анимирует исходную картинку. GIF в качестве исходника тоже можно передать — будет использован его первый кадр.
Прозрачный фон — background: "transparent".
Ограничения. n — не больше 4; output_compression и stream не поддерживаются. Другие модели output_format: "gif" не принимают.
Цена — по токенам изображения, как у обычной генерации. Для кадра 512×512 в качестве low: около 550 токенов за 4 кадра, 1 200 — за 9, 1 700 — за 16; medium дороже примерно в 1,8 раза, high — в 2,1.

Редактирование и вариации (image-to-image)

Передайте исходные картинки в input_references — модель доработает их по промпту. Каждый элемент — объект { "type": "image_url", "image_url": { "url": "..." } }, где url — публичный URL или data URI в base64. Картинку, загруженную через Files API, можно указать по идентификатору: { "type": "file", "file": { "file_id": "rai_file_…" } }.

curl https://routerai.ru/api/v1/images \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "Сделай фон закатным и добавь тёплое освещение",
    "input_references": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/photo.png" }
      }
    ]
  }'

Чтобы передать локальный файл, закодируйте его в base64 и используйте data URI:

IMAGE_BASE64=$(base64 -w 0 photo.png)

curl https://routerai.ru/api/v1/images \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d "{
    \"model\": \"openai/gpt-image-2\",
    \"prompt\": \"Сделай фон закатным\",
    \"input_references\": [
      {
        \"type\": \"image_url\",
        \"image_url\": { \"url\": \"data:image/png;base64,$IMAGE_BASE64\" }
      }
    ]
  }"

Правка по маске

Модели openai/gpt-image-* принимают поле mask (PNG с альфа-каналом, прозрачные пиксели отмечают область правки; только вместе с input_references), но точного inpaint, как у DALL·E 2, не выполняют. Маску OpenAI использует лишь как подсказку и заново генерирует весь кадр. На практике маска то не влияет на результат, то оставляет выделенную область залитой чёрным.

Чтобы изменить часть изображения, передайте исходник в input_references без маски и опишите в prompt, что изменить и что сохранить:

IMAGE_BASE64=$(base64 -w 0 photo.png)

curl https://routerai.ru/api/v1/images \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d "{
    \"model\": \"openai/gpt-image-2\",
    \"prompt\": \"Замени вазу на столе на букет тюльпанов, всё остальное оставь без изменений\",
    \"input_references\": [
      { \"type\": \"image_url\", \"image_url\": { \"url\": \"data:image/png;base64,$IMAGE_BASE64\" } }
    ]
  }"

openai/gpt-image-2 при такой правке меняет только названный объект, остальной кадр сохраняется практически без изменений.

Формат ответа

Ответ содержит метку времени created, массив data с изображениями в base64 (b64_json) и usage со стоимостью запроса в рублях:

{
  "created": 1735689600,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "cost": 3.4
  }
}

Сохранение изображения

Извлеките base64 из ответа и декодируйте в файл:

# Ответ сохранён в response.json
cat response.json | jq -r '.data[0].b64_json' | base64 -d > image.png

Диалоговые модели генерации изображений

Некоторые модели генерируют картинки прямо в диалоге и работают через /api/v1/chat/completions с параметром modalities, включающим "image" и "text". Изображения возвращаются в поле images сообщения ассистента. Это, в частности, модели Gemini (google/gemini-2.5-flash-image и др.), которые помнят контекст переписки.

curl https://routerai.ru/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d '{
    "model": "google/gemini-2.5-flash-image",
    "messages": [
      { "role": "user", "content": "Создай красивый закат над горами" }
    ],
    "modalities": ["image", "text"],
    "image_config": {
      "aspect_ratio": "16:9",
      "image_size": "4K"
    }
  }'

Модели Gemini поддерживают дополнительную настройку через image_config (aspect_ratio, image_size: 1K/2K/4K). Изображения приходят как base64 data URL в choices[0].message.images[]:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Готово!",
        "images": [
          {
            "type": "image_url",
            "image_url": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }
          }
        ]
      }
    }
  ]
}

Картинка всегда приходит в images, а не в content. Если модель ответила только изображением без текста, content равен null — так часто отвечает google/gemini-3-pro-image. Проверяйте images, а не наличие текста.

Без modalities картинку по умолчанию запрашивают только у моделей Gemini, предназначенных для генерации изображений; у остальных диалоговых моделей с выводом изображений передавайте "modalities": ["image", "text"] явно.

При "stream": true изображение приходит целиком в одном из чанков, в choices[0].delta.images[] в том же формате:

{
  "choices": [
    {
      "delta": {
        "images": [
          {
            "type": "image_url",
            "image_url": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }
          }
        ]
      }
    }
  ]
}

Клиенты, которые разбирают только delta.content (часть OpenAI-совместимых SDK и IDE-плагинов), такую картинку не покажут.

Параметры `image_config` (Gemini)

aspect_ratio — соотношение сторон, по умолчанию 1:1. Итоговое разрешение зависит от поколения модели:

`aspect_ratio`	Gemini 3.x, тир `1K`	`gemini-2.5-flash-image`
`1:1`	1024×1024	1024×1024
`2:3` / `3:2`	848×1264 / 1264×848	832×1248 / 1248×832
`3:4` / `4:3`	896×1200 / 1200×896	864×1184 / 1184×864
`4:5` / `5:4`	928×1152 / 1152×928	896×1152 / 1152×896
`9:16` / `16:9`	768×1376 / 1376×768	768×1344 / 1344×768
`21:9`	1584×672	1536×672
`1:4` / `4:1`	512×2064 / 2064×512	—
`1:8` / `8:1`	352×2928 / 2928×352	—

Gemini 3.x — это gemini-3-pro-image, gemini-3.1-flash-image, gemini-3.1-flash-lite-image, gemini-nano-banana-2.1 и их -preview. Вытянутые форматы 1:4, 4:1, 1:8, 8:1 есть у всех, кроме gemini-3-pro-image.

image_size — тир разрешения: 1K (по умолчанию), 2K, 4K; у gemini-3.1-flash-image и -preview также 512. Размер из таблицы умножается на тир: 2K — ×2 (16:9 → 2752×1536), 4K — ×4 (16:9 → 5504×3072), 512 — ×0,5 (16:9 → 688×384). gemini-3.1-flash-lite-image и gemini-2.5-flash-image работают только в 1K. Поддерживается только моделями Gemini.

Какой эндпоинт использует конкретная модель, указано в блоке Эндпоинт на её странице.

Лучшие практики

Подробные промпты. Чем точнее описание (стиль, композиция, освещение), тем лучше результат.
Параметры под задачу. Прозрачный фон — background: "transparent" + output_format: "png"; меньший вес файла — jpeg/webp с output_compression.
Итеративная доработка. Чтобы изменить уже сгенерированную картинку, передайте её в input_references следующего запроса (image-to-image).
Хранение. Изображения приходят в base64 — продумайте декодирование и хранение.

Устранение неполадок

Ошибка «model not served» или 503?

Убедитесь, что у модели есть "image" в output_modalities (см. страницу моделей).

Пустой data в ответе?

Проверьте, что промпт описывает желаемое изображение, а параметры (size, aspect_ratio, quality) поддерживаются моделью.

Нужна правка изображения, а не генерация с нуля?

Передайте исходник в input_references. Для правки prompt описывает требуемые изменения.