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

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

RouterAI предоставляет выделенный эндпоинт POST /api/v1/images для синхронной генерации изображений. Запрос принимает текстовый промпт и сразу возвращает готовые изображения в формате base64. Эндпоинт поддерживают модели, у которых есть "image" в списке output_modalities (например, openai/gpt-image-1, 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-1",
    "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-1",
        "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-1`).
`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`.
`background`	string	Фон: `auto`, `transparent`, `opaque`.
`output_format`	string	Формат вывода: `png`, `jpeg`, `webp`.
`output_compression`	integer	Степень сжатия `0–100` для `jpeg`/`webp`.
`seed`	integer	Сид для воспроизводимости результата.
`input_references`	array	Исходные изображения для image-to-image (правка/вариации).
`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. Допустимый набор зависит от модели.

Разрешение (resolution). Тиры качества: 512, 1K, 2K, 4K.

Качество (quality). auto (по умолчанию у большинства), low, medium, high.

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

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

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

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

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

Потоковая генерация

С "stream": true ответ приходит как поток Server-Sent Events: события image_generation.partial_image (превью по мере готовности) и финальное image_generation.completed (полный результат с usage), затем [DONE].

curl https://routerai.ru/api/v1/images \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "Футуристический город на закате",
    "stream": true
  }'

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

Ответ содержит метку времени 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..." }
          }
        ]
      }
    }
  ]
}

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

aspect_ratio — соотношение сторон → итоговое разрешение (на тире 1K): 1:1 → 1024×1024 (по умолчанию), 2:3 → 832×1248, 3:2 → 1248×832, 3:4 → 864×1184, 4:3 → 1184×864, 4:5 → 896×1152, 5:4 → 1152×896, 9:16 → 768×1344, 16:9 → 1344×768, 21:9 → 1536×672.
image_size — масштаб разрешения: 1K (по умолчанию), 2K, 4K. Поддерживается только моделями 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 описывает требуемые изменения.