# POST /images/generations

Генерация изображений по текстовому описанию в формате OpenAI. Тело запроса, ответ, цена и ошибки.

`POST /api/v1/images/generations` (нужен API-ключ)

Создает изображения по описанию — как `client.images.generate` в OpenAI SDK. Модели генерации изображений перечислены в [каталоге](/models?kind=image) и в `GET /api/v1/models?output_modalities=image`. Машиночитаемый контракт: [openapi.yaml](/docs/openapi.yaml).

## Тело запроса

| Поле                                                                                   | Тип     |                                                                                                                               |
| -------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `model`                                                                                | string  | Обязательно. ID модели генерации изображений.                                                                                 |
| `prompt`                                                                               | string  | Обязательно. Что нарисовать. Если ключ маскирует данные, описание маскируется так же, как текст чата.                         |
| `n`                                                                                    | integer | Сколько изображений, по умолчанию 1. Не больше лимита модели (`routes[].max_completion_tokens` в `GET /models`), иначе `400`. |
| `response_format`                                                                      | string  | Только `b64_json`: изображения приходят в base64. `url` дает `400`.                                                           |
| `provider`                                                                             | object  | `only`, `ignore`, `order`, `zdr`, `data_collection`, как в [chat completions](/docs/ru/api/chat-completions).                 |
| `size`, `quality`, `resolution`, `aspect_ratio`, `output_format`, `background`, `seed` |         | Передаются провайдеру; какие из них поддерживает модель, указано на ее странице в каталоге.                                   |

`stream`, `input_references`, `image` и `mask` (потоковая генерация и редактирование по изображению) не поддерживаются: `400`.

## Ответ

```json
{
  "created": 1793641748,
  "data": [{ "b64_json": "iVBORw0KGgo…", "media_type": "image/jpeg" }],
  "usage": { "prompt_tokens": 3, "completion_tokens": 4175, "total_tokens": 4178, "cost": 0.0088 }
}
```

| Поле                |                                                              |
| ------------------- | ------------------------------------------------------------ |
| `data[].b64_json`   | Изображение в base64.                                        |
| `data[].media_type` | `image/png`, `image/jpeg`, `image/webp` или `image/svg+xml`. |
| `usage.cost`        | Сумма списания в PnP.                                        |

ID генерации — в заголовке ответа `X-Generation-Id`; по нему [GET /generation](/docs/ru/api/generation) возвращает стоимость и попытки.

## Цена

Модели берут плату за изображение (часто в зависимости от разрешения), за мегапиксель или за токены изображения; цена указана на странице модели в каталоге. Списывается фактическая стоимость вызова. Перед запросом резервируется худший случай: `n` изображений по самой дорогой цене модели. В журнале кабинета у вызова указано число изображений.

## Пример

```bash
curl https://router.nodul.ru/api/v1/images/generations \
  -H "Authorization: Bearer $NODUL_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "global-1/black-forest-labs/flux-3-image-klein", "prompt": "A red fox in the snow, watercolor"}' \
  | jq -r '.data[0].b64_json' | base64 --decode > image.png
```

```python
import base64
import os

from openai import OpenAI

client = OpenAI(base_url="https://router.nodul.ru/api/v1", api_key=os.environ["NODUL_ROUTER_API_KEY"])
response = client.images.generate(
    model="global-1/black-forest-labs/flux-3-image-klein",
    prompt="A red fox in the snow, watercolor",
)
with open("image.png", "wb") as f:
    f.write(base64.b64decode(response.data[0].b64_json))
```

## Ошибки

| Код   | Когда                                                                                                                                                                                      |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | Неверное тело, модель не генерирует изображения (`Model … does not support this endpoint.`), `n` больше лимита модели, `response_format` не `b64_json`, `stream` или изображения на входе. |
| `402` | Баланса или лимита ключа не хватает на резерв.                                                                                                                                             |
| `403` | Модель недоступна ключу, пространство разрешает только модели в России.                                                                                                                    |