POST /images/generations

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

POST/api/v1/images/generationsAPI-ключ

Создает изображения по описанию — как client.images.generate в OpenAI SDK. Модели генерации изображений перечислены в каталоге и в GET /api/v1/models?output_modalities=image. Машиночитаемый контракт: 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.
`size`, `quality`, `resolution`, `aspect_ratio`, `output_format`, `background`, `seed`		Передаются провайдеру; какие из них поддерживает модель, указано на ее странице в каталоге.

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

Ответ

{
  "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 возвращает стоимость и попытки.

Цена

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

Пример

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

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`	Модель недоступна ключу, пространство разрешает только модели в России.