Документация / API

Изображения

Генерация изображений по описанию.

Ключ — в заголовке Authorization: Bearer <ключ>. Как получить ключ →

POST/v1/images

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

Создаёт изображения по текстовому описанию и возвращает их в base64. Резерв — на все n изображений по наибольшему размеру, который допускает модель; списывается фактическая стоимость. Модели, которые берут плату за токены изображения, пока не обслуживаются.

Запрос

curl https://api.aireplica.ru/v1/images \
  -H "Authorization: Bearer $AIREPLICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "aspect_ratio": "16:9",
  "model": "google/gemini-2.5-flash-image",
  "n": 1,
  "prompt": "Красный велосипед на белом фоне, студийный свет"
}'

Ответ 200

{
  "created": 1760270000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo="
    }
  ],
  "usage": {
    "cost": 3.47,
    "cost_status": "final"
  }
}

Тело запроса

application/json

aspect_ratiostring
Соотношение сторон: 1:1, 16:9, 9:16, 4:3, 3:2 и другие; модель берёт ближайшее из тех, что умеет.
backgroundstring
Фон; transparent — только с output_format png или webp.
Значения:autotransparentopaque
modelstringобязательное
ID модели изображений из каталога, например google/gemini-2.5-flash-image.
ninteger
Сколько изображений сделать. Больше, чем допускает модель, — отказ 400; резерв — на все n.
По умолчанию: 1. Не меньше 1.
output_compressioninteger
Сжатие для jpeg и webp: 100 — без потерь качества.
Не меньше 0. Не больше 100.
output_formatstring
Формат файла изображения; svg — только у моделей векторизации, разметка SVG приходит в b64_json.
Значения:pngjpegwebpsvg
promptstringобязательное
Описание изображения: что изображено, стиль, свет, композиция.
qualitystring
Качество отрисовки. Модели без такой настройки её не учитывают.
Значения:autolowmediumhighxhighmax
resolutionstring
Ступень разрешения: 512, 768, 1K, 1.5K, 2K или 4K; точный размер в пикселях выбирает модель.
seedinteger
Зерно случайности для повторяемого результата. Поддерживают не все модели.
sizestring
Размер одной строкой: ступень (2K) или пиксели (2048x2048). Заменяет resolution и aspect_ratio.

Другие поля формата OpenRouter модель получает без изменений.

Ответ 200

application/json

Изображения в base64.

createdinteger
Время создания, Unix-секунды.
dataarray of objectобязательное
Изображения; провайдер может вернуть меньше, чем n.
Поля элемента · 1
- b64_jsonstring
  Файл изображения в base64.
usageobject
Расход и стоимость запроса.
Поля объекта · 5
- completion_tokensinteger
  Токенов в ответе, включая рассуждения модели.
- costnumber | null
  Списанная сумма в рублях, пять знаков после точки (тысячные доли копейки). null, пока стоимость уточняется (pending) или списание на проверке (review).
- cost_statusstring
  Как определена стоимость: final — по фактической цене провайдера; estimated — по нашему прайсу; pending — уточняется, списание будет позже; review — решает оператор.
  Значения:finalestimatedpendingreview
- prompt_tokensinteger
  Токенов во входе.
- total_tokensinteger
  Всего токенов.

Ошибки

400Запрос неверен или его стоимость нельзя ограничить заранее. Ничего не списано; параметр — в metadata.param.

401Ключ не передан, неверен или отозван, либо аккаунт приостановлен.

402Баланса не хватает на резерв этого запроса.

403Входные данные не прошли модерацию; причины — в metadata.reasons.

404413422Провайдер модели отклонил запрос; его статус сохраняется (400, 404, 413 или 422), объяснение провайдера — в metadata.provider_message.

429Слишком много запросов или провайдер модели перегружен. Повторите позже; заголовок Retry-After, если он есть, говорит, через сколько секунд.

502Провайдер модели не ответил или вернул ошибку.

503Списания или провайдер модели временно недоступны. Повторите позже.

Тело ошибки — {"error": {"code", "message", "metadata"}}; что делать — Лимиты и ошибки.