API

Нейросети Riflect
в вашем коде

Открытый REST API: генерируйте картинки в Nano Banana 2.1, GPT Image 2.6 и 2.5 из своих сервисов, ботов и скриптов. Вход по личному ключу, оплата кредитами вашего баланса, работает из России без VPN.

Быстрый старт

Запуск сразу возвращает номер работы. Готовность узнаётся опросом или вебхуком.

Базовый адрес: https://riflect.ru/api/v1. Все запросы и ответы в JSON (UTF-8).

1. Запустите генерацию

curl https://riflect.ru/api/v1/images/generations \
  -H "Authorization: Bearer rfl_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-1",
    "prompt": "Рыжая лиса в осеннем лесу, мягкий утренний свет",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }'

Ответ приходит сразу, работа ещё идёт

HTTP/1.1 201 Created

{
  "data": [
    {
      "id": "3f0c2a8e-5b1d-4a57-9d0e-1c2b3a4d5e6f",
      "status": "pending",
      "model": "nano-banana-2-1",
      "credits": 4,
      "created_at": "2026-11-16T12:00:00+00:00"
    }
  ],
  "credits_left": 996
}

2. Узнайте результат: спрашивайте статус раз в несколько секунд или получите вебхук

curl https://riflect.ru/api/v1/generations/3f0c2a8e-5b1d-4a57-9d0e-1c2b3a4d5e6f \
  -H "Authorization: Bearer rfl_ваш_ключ"

Готовая работа

{
  "id": "3f0c2a8e-5b1d-4a57-9d0e-1c2b3a4d5e6f",
  "status": "succeeded",
  "model": "nano-banana-2-1",
  "credits": 4,
  "created_at": "2026-11-16T12:00:00+00:00",
  "images": [{ "url": "https://…" }]
}

Пример на Python: запуск и опрос статуса

import time, requests

API = "https://riflect.ru/api/v1"
HEADERS = {"Authorization": "Bearer rfl_ваш_ключ"}

job = requests.post(f"{API}/images/generations", headers=HEADERS, json={
    "model": "gpt-2-5-flare",
    "prompt": "Логотип кофейни «Зерно», плоский стиль",
    "background": "transparent",
}).json()["data"][0]

while job["status"] == "pending":
    time.sleep(3)  # картинка обычно готова за 10–40 секунд
    job = requests.get(f"{API}/generations/{job['id']}", headers=HEADERS).json()

print(job["images"] if job["status"] == "succeeded" else job["error"])

Ключи

Каждый запрос передаёт личный ключ в заголовке Authorization: Bearer rfl_…

Ключ создаётся в блоке «Ваши ключи» ниже (он общий для API и MCP) и виден один раз. Генерации списывают кредиты с баланса владельца ключа. Удалённый ключ перестаёт работать сразу, при смене пароля отключаются все ключи. Не вставляйте ключ в код сайта или приложения, который видят пользователи: вызывайте API со своего сервера.

Ваши ключи

Ключ общий для API и MCP. Он даёт доступ к вашему балансу и работам: храните его на своём сервере и не публикуйте.

    Статусы

    Поле status в ответе запуска, GET /generations/{id} и в вебхуке.

    • pending

      Работа в очереди, генерируется или мы копируем готовый файл в хранилище. Ссылок ещё нет.

    • succeeded

      Готово: в поле images ссылки на файлы.

    • failed

      Не получилось: причина в поле error, кредиты за работу уже вернулись на баланс.

    Статус меняется только из pending в succeeded или failed. Сервер всегда отвечает сразу текущим статусом: если работа ещё идёт, спросите снова через несколько секунд.

    Методы

    POST /images/generations

    Запуск генерации картинок. Кредиты списываются сразу, ответ 201 приходит без ожидания результата: в data столько работ, сколько вариантов просили (n), у каждой свой id. Поля запроса общие для всех моделей, допустимые значения у каждой модели свои (раздел «Модели»).

    model
    Тип
    string
    По умолчанию
    обязательно
    Значения
    nano-banana-2-1, gpt-2-6-flare, gpt-2-6-sunburst, gpt-2-5-flare, gpt-2-5-sunburst
    Описание
    Модель.
    prompt
    Тип
    string
    По умолчанию
    обязательно
    Значения
    1–6000 знаков
    Описание
    Что нарисовать или как изменить фото, на любом языке.
    aspect_ratio
    Тип
    string
    По умолчанию
    auto
    Значения
    см. модель
    Описание
    Формат кадра.
    resolution
    Тип
    string
    По умолчанию
    1K
    Значения
    1K, 2K, 4K
    Описание
    Разрешение. От него зависит цена.
    n
    Тип
    integer
    По умолчанию
    1
    Значения
    1–4
    Описание
    Сколько вариантов. Каждый вариант это отдельная работа со своим id и своей ценой.
    images
    Тип
    string[]
    По умолчанию
    []
    Значения
    до 10 или 16, см. модель
    Описание
    Фото-референсы: ссылка https, строка data:image/png;base64,… (также jpeg, webp) или id вашей прошлой работы. Фото до 10 МБ.
    callback_url
    Тип
    string
    По умолчанию
    нет
    Значения
    https-адрес
    Описание
    Куда прислать вебхук, когда работа закончится. Только https на порт 443 и публичный адрес.

    Ответ 201

    {
      "data": [
        {
          "id": "3f0c2a8e-5b1d-4a57-9d0e-1c2b3a4d5e6f",
          "status": "pending",
          "model": "nano-banana-2-1",
          "credits": 4,
          "created_at": "2026-11-16T12:00:00+00:00"
        }
      ],
      "credits_left": 996
    }

    GET /generations/{id}

    Текущий статус работы и ссылки на файлы. Отвечает сразу. Свежие ссылки выдаются при каждом запросе.

    Ответ 200: готово

    {
      "id": "3f0c2a8e-5b1d-4a57-9d0e-1c2b3a4d5e6f",
      "status": "succeeded",
      "model": "nano-banana-2-1",
      "credits": 4,
      "created_at": "2026-11-16T12:00:00+00:00",
      "images": [{ "url": "https://…" }]
    }

    Ответ 200: ошибка (кредиты вернулись)

    {
      "id": "3f0c2a8e-5b1d-4a57-9d0e-1c2b3a4d5e6f",
      "status": "failed",
      "model": "nano-banana-2-1",
      "credits": 4,
      "created_at": "2026-11-16T12:00:00+00:00",
      "error": "Запрос не прошёл проверку содержимого. Измените описание или фото и попробуйте снова. Кредиты возвращены"
    }

    GET /models

    Модели API с ценами в кредитах по разрешению, форматами кадра, числом фото-референсов и параметрами. Те же данные, что в разделе «Модели», в машинном виде.

    Ответ 200

    {
      "models": [
        {
          "id": "nano-banana-2-1",
          "title": "Nano Banana 2.1",
          "credits_by_resolution": { "1K": 3, "2K": 4, "4K": 5 },
          "max_images": 10,
          "aspect_ratios": ["auto", "1:1", "2:3", "…"],
          "resolutions": ["1K", "2K", "4K"],
          "parameters": [
            { "key": "output_format", "label": "Формат файла", "type": "select", "default": "png", "values": ["png", "jpg"] }
          ]
        }
      ]
    }

    GET /balance

    Остаток кредитов на балансе.

    Ответ 200

    { "credits": 996 }

    GET /webhook-secret

    Секрет подписи вебхуков вашего аккаунта (создаётся при первом запросе). POST /webhook-secret/rotate выдаёт новый, старый перестаёт подходить сразу.

    Ответ 200

    { "secret": "whsec_…" }

    Модели

    Цена указана за одну картинку в кредитах. Другие модели Riflect появятся в API позже.

    Nano Banana 2.1

    nano-banana-2-1

    Быстрая и недорогая модель Google. Хорошо держит лицо и детали с фото-референсов, подходит для правки фото, вариаций и коллажей.

    Цена за картинку

    • 1K3 кредитов
    • 2K4 кредитов
    • 4K5 кредитов

    Фото-референсы

    до 10 в поле images

    resolution

    1K, 2K, 4K

    aspect_ratio

    auto1:12:33:21:44:13:44:34:55:41:88:19:1616:921:9

    Параметры модели (в дополнение к общим полям)

    output_format
    Тип
    string
    По умолчанию
    png
    Значения
    png, jpg
    Описание
    Формат файла результата.
    • auto: формат кадра модель выбирает сама.

    Пример тела запроса POST /images/generations

    {
      "model": "nano-banana-2-1",
      "prompt": "Та же девушка с фото, но в осеннем лесу, мягкий утренний свет",
      "images": ["https://example.com/portrait.jpg"],
      "aspect_ratio": "3:4",
      "resolution": "2K",
      "output_format": "jpg"
    }

    GPT Image 2.6 Flare

    gpt-2-6-flare

    Новая версия GPT Image от OpenAI. Точнее пишет текст, лучше собирает макеты и постеры, держит правки фото. Качество выбирается полем quality.

    Цена за картинку

    • 1K5 кредитов
    • 2K9 кредитов
    • 4K15 кредитов

    Фото-референсы

    до 16 в поле images

    resolution

    1K, 2K, 4K

    aspect_ratio

    auto1:13:22:34:33:45:44:516:99:162:11:221:99:213:11:3

    Параметры модели (в дополнение к общим полям)

    quality
    Тип
    string
    По умолчанию
    medium
    Значения
    low, medium, high, xhigh, max
    Описание
    Качество. Чем выше, тем детальнее картинка и тем она дороже, цена зависит от качества и разрешения.
    background
    Тип
    string
    По умолчанию
    auto
    Значения
    auto, opaque, transparent
    Описание
    Фон картинки. transparent даёт PNG без заднего плана. Поле работает только при resolution 1K, с 2K и 4K запрос вернёт 400.
    • Цена в кредитах за картинку по качеству (1K / 2K / 4K): low 3 / 5 / 9, medium 5 / 9 / 15, high 6 / 11 / 18, xhigh 10 / 19 / 31, max 21 / 42 / 70. В карточке цен выше указано качество medium.
    • С фото-референсами модель правит или перерисовывает их по описанию, без них рисует с нуля.

    Пример тела запроса POST /images/generations

    {
      "model": "gpt-2-6-flare",
      "prompt": "Баннер распродажи кроссовок, надпись «−30% до воскресенья», чистый минимализм",
      "aspect_ratio": "3:1",
      "resolution": "2K",
      "quality": "high"
    }

    GPT Image 2.6 Sunburst

    gpt-2-6-sunburst

    Вторая версия GPT Image 2.6: те же параметры и цена, другой характер картинки. Хорошо держит лицо и детали при правке фото.

    Цена за картинку

    • 1K5 кредитов
    • 2K9 кредитов
    • 4K15 кредитов

    Фото-референсы

    до 16 в поле images

    resolution

    1K, 2K, 4K

    aspect_ratio

    auto1:13:22:34:33:45:44:516:99:162:11:221:99:213:11:3

    Параметры модели (в дополнение к общим полям)

    quality
    Тип
    string
    По умолчанию
    medium
    Значения
    low, medium, high, xhigh, max
    Описание
    Качество. Чем выше, тем детальнее картинка и тем она дороже, цена зависит от качества и разрешения.
    background
    Тип
    string
    По умолчанию
    auto
    Значения
    auto, opaque, transparent
    Описание
    Фон картинки. transparent даёт PNG без заднего плана. Поле работает только при resolution 1K, с 2K и 4K запрос вернёт 400.
    • Цена в кредитах за картинку по качеству (1K / 2K / 4K): low 3 / 5 / 9, medium 5 / 9 / 15, high 6 / 11 / 18, xhigh 10 / 19 / 31, max 21 / 42 / 70. В карточке цен выше указано качество medium.
    • С фото-референсами модель правит или перерисовывает их по описанию, без них рисует с нуля.

    Пример тела запроса POST /images/generations

    {
      "model": "gpt-2-6-sunburst",
      "prompt": "Наклейка: рыжий кот в очках, толстая белая обводка",
      "aspect_ratio": "1:1",
      "resolution": "1K",
      "quality": "medium",
      "background": "transparent"
    }

    GPT Image 2.5 Flare

    gpt-2-5-flare

    Модель OpenAI. Точно пишет текст на картинке, понимает длинные подробные описания, умеет прозрачный фон.

    Цена за картинку

    • 1K4 кредитов
    • 2K6 кредитов
    • 4K9 кредитов

    Фото-референсы

    до 16 в поле images

    resolution

    1K, 2K, 4K

    aspect_ratio

    auto1:13:22:34:33:416:99:1621:927:1616:279:88:9

    Параметры модели (в дополнение к общим полям)

    background
    Тип
    string
    По умолчанию
    auto
    Значения
    auto, opaque, transparent
    Описание
    Фон картинки. transparent даёт PNG без заднего плана (логотипы, стикеры, предметы для вырезки).
    • Форматы 27:16, 16:27, 9:8 и 8:9 модель делает только в 1K: для них resolution игнорируется, а цена берётся как за 1K.
    • С фото-референсами модель правит или перерисовывает их по описанию, без них рисует с нуля.

    Пример тела запроса POST /images/generations

    {
      "model": "gpt-2-5-flare",
      "prompt": "Логотип кофейни «Зерно»: зерно кофе и надпись, плоский стиль",
      "aspect_ratio": "1:1",
      "resolution": "1K",
      "background": "transparent",
      "n": 2
    }

    GPT Image 2.5 Sunburst

    gpt-2-5-sunburst

    Вторая версия GPT Image 2.5: те же параметры и цена, другой характер картинки. Удобно сравнить с Flare на одном описании.

    Цена за картинку

    • 1K4 кредитов
    • 2K6 кредитов
    • 4K9 кредитов

    Фото-референсы

    до 16 в поле images

    resolution

    1K, 2K, 4K

    aspect_ratio

    auto1:13:22:34:33:416:99:1621:927:1616:279:88:9

    Параметры модели (в дополнение к общим полям)

    background
    Тип
    string
    По умолчанию
    auto
    Значения
    auto, opaque, transparent
    Описание
    Фон картинки. transparent даёт PNG без заднего плана (логотипы, стикеры, предметы для вырезки).
    • Форматы 27:16, 16:27, 9:8 и 8:9 модель делает только в 1K: для них resolution игнорируется, а цена берётся как за 1K.
    • С фото-референсами модель правит или перерисовывает их по описанию, без них рисует с нуля.

    Пример тела запроса POST /images/generations

    {
      "model": "gpt-2-5-sunburst",
      "prompt": "Постер фестиваля уличной еды, крупная надпись «ВКУСНО», яркие цвета",
      "aspect_ratio": "2:3",
      "resolution": "2K"
    }

    Вебхуки

    Чтобы не опрашивать статус, передайте callback_url при запуске.

    Когда работа закончится (succeeded или failed), сервер отправит POST на callback_url. Тело такое же, как ответ GET /generations/{id}, плюс поле event: generation.succeeded или generation.failed. При n больше 1 уведомление приходит по каждой работе отдельно.

    Ответьте любым кодом 2xx в течение 10 секунд, тело ответа не читается. Если получатель недоступен или ответил не 2xx, отправка повторяется через 30 секунд, 2, 10, 30 и 60 минут, всего шесть попыток. Перенаправления не выполняются.

    Одно уведомление может прийти повторно (например, если ваш сервер ответил слишком поздно): заголовок X-Riflect-Delivery у повторов тот же, по нему удобно отбрасывать дубли.

    Запрос, который приходит на ваш сервер

    POST https://your-server.example/riflect-hook
    Content-Type: application/json
    User-Agent: Riflect-Webhooks/1.0
    X-Riflect-Event: generation.succeeded
    X-Riflect-Delivery: 1842
    X-Riflect-Timestamp: 1794830400
    X-Riflect-Signature: sha256=5d41402abc4b2a76b9719d911017c592…
    
    {
      "event": "generation.succeeded",
      "id": "3f0c2a8e-5b1d-4a57-9d0e-1c2b3a4d5e6f",
      "status": "succeeded",
      "model": "nano-banana-2-1",
      "credits": 4,
      "created_at": "2026-11-16T12:00:00+00:00",
      "images": [{ "url": "https://…" }]
    }

    Проверка подписи

    Подпись это HMAC-SHA256 секретом аккаунта (GET /webhook-secret) от строки «X-Riflect-Timestamp, точка, тело запроса как есть». Проверяйте её до разбора JSON и отклоняйте старые уведомления: так подделать или повторить чужой запрос не выйдет.

    import hashlib, hmac, time
    
    SECRET = "whsec_…"  # GET /v1/webhook-secret
    
    def verify(headers, raw_body: bytes) -> bool:
        ts = headers["X-Riflect-Timestamp"]
        if abs(time.time() - int(ts)) > 300:  # старше 5 минут: не принимаем
            return False
        expected = hmac.new(SECRET.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
        return hmac.compare_digest(headers["X-Riflect-Signature"], "sha256=" + expected)
    import crypto from "node:crypto";
    
    const SECRET = "whsec_…"; // GET /v1/webhook-secret
    
    export function verify(headers, rawBody /* Buffer */) {
      const ts = headers["x-riflect-timestamp"];
      if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
      const expected = crypto.createHmac("sha256", SECRET).update(ts + ".").update(rawBody).digest("hex");
      const got = Buffer.from(headers["x-riflect-signature"] ?? "");
      const want = Buffer.from("sha256=" + expected);
      return got.length === want.length && crypto.timingSafeEqual(got, want);
    }

    Ошибки

    Код ответа 4xx или 5xx и тело {"error": "текст"}. С заголовком Accept-Language: en текст приходит по-английски, если перевод есть.

    400Неверные параметры: в error написано, какое поле и что не так. Неизвестные поля тоже дают 400.
    401Нет заголовка Authorization, ключ неверный или удалён.
    402Не хватает кредитов на балансе.
    404Работа не найдена (или она чужая).
    413Запрос или фото слишком большие: тело до 60 МБ, каждое фото до 10 МБ.
    415Файл по ссылке или в base64 не JPG, PNG или WebP.
    429Слишком много запросов или одновременных генераций: подождите и повторите.
    503Сервер занят: повторите через несколько секунд.

    Пример

    HTTP/1.1 400 Bad Request
    
    { "error": "aspect_ratio: auto, 1:1, 2:3, 3:2, …" }

    Лимиты

    • 60 запросов в минуту с одного ключа и 120 в минуту на аккаунт по всем ключам.
    • Одновременных генераций столько, сколько разрешает ваш тариф (как на сайте); до 3 запусков, которые сервер обрабатывает одновременно.
    • Фото-референсов по ссылкам и в base64 не больше 30 в час на аккаунт (каждое фото считается загрузкой). Id ваших прошлых работ в этот лимит не входят.
    • Ссылки на результат действуют около двух часов: файл нужно скачать. Свежую ссылку отдаёт GET /generations/{id}.

    Нужна другая модель или что-то не работает? Напишите в поддержку