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

> Генерируйте изображения с помощью 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` — см. раздел «Диалоговые модели генерации изображений» ниже.

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

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

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

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

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

### В чате

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

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

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

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

```bash
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:

```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. |

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

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

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

```bash
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.

```bash
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:

```bash
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]`.

```bash
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` со стоимостью запроса в рублях:

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

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

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

```bash
# Ответ сохранён в 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` и др.), которые помнят контекст переписки.

```bash
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[]`:

```json
{
  "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` (см. [страницу моделей](/models)).

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

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

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

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