Rivya API — контракт для разработчиков, позволяющий использовать поддерживаемые возможности моделей Rivya в собственном продукте, скрипте или процессе, когда доступ к Public API включен для развертывания и открыт вашему аккаунту.
Это не отдельный от Rivya Studio продукт. Он использует ту же границу аккаунта, тот же кредитный кошелек и тот же публичный слой моделей, который пользователи видят в Rivya. Разница в том, как начинается работа: вместо кликов в Studio ваше приложение отправляет запросы с API key.
Если нужны детали endpoints, начните с Обзор Rivya API и Быстрый старт Rivya API. Эта статья объясняет продуктовый уровень: для чего нужен API, где он уместен и когда он не должен быть первым путем.
Короткая версия
Rivya API v1 позволяет подходящему вошедшему аккаунту создавать API-ключи и вызывать готовые к API модели Rivya вне веб-интерфейса. Страницы для разработчиков описывают реализованный контракт; возможность запуска зависит от активного развертывания, прав аккаунта и готовности модели.
Реализованная поверхность API включает:
поиск моделей через список API
асинхронные задачи генерации изображений, видео и аудио
загрузки через Files API для моделей, которым нужны референсные медиа
опрос состояния генерации по публичным идентификаторам задач
проверки кредитов аккаунта
обращения к Chat API, включая необязательную потоковую передачу SSE
подписанные вебхуки завершения генерации, если вебхуки включены в развертывании
бета-версия TypeScript SDK для команд, которым нужна готовая клиентская оболочка
Публичный раздел для разработчиков — Developers. Начните с него, если нужен обзор, ссылки на настройку ключа API и безопасный порядок отладки.
Зачем Rivya нужен API
Studio полезна, когда человек все еще выбирает модели, формирует промпты, проверяет результаты и решает, что делать дальше.
API полезен, когда решение превратилось в повторяемый продуктовый или операционный процесс.
Распространенные примеры при включенном доступе к API:
продукт хочет генерировать варианты изображений после того, как пользователь отправил бриф
маркетинговый процесс должен создавать визуальные черновики из структурированных данных кампании
внутреннему инструменту нужно отправлять задачи видео или аудио без просьбы открыть браузер
система поддержки или управления материалами должна выполнять один ход чат-модели в собственном интерфейсе
серверная служба должна получать подписанные обратные вызовы после завершения задач генерации
В таких случаях Rivya API сохраняет работу внутри того же аккаунта Rivya, вместо того чтобы заставлять команду строить отдельный стек для биллинга, выбора модели и статуса задач.
Что API не заменяет
API не заменяет все причины использовать Rivya напрямую.
Используйте Руководство Rivya Studio или публичные рабочие поверхности, когда:
промпт все еще требует человеческого исследования
выбор модели нестабилен
автор должен визуально сравнивать результаты
проект зависит от сохраненной истории и ручной проверки
команда еще не решила, какой формат входа и выхода должен стать повторяемым
Используйте API, когда процесс уже достаточно ясен для автоматизации.
Эта граница важна. Расплывчатый творческий вопрос обычно сначала принадлежит Studio. Известный продуктовый поток с предсказуемыми входными данными может перейти в API.
Основные строительные блоки
Думайте об API как о шести связанных частях.
| Блок | За что отвечает | Что читать дальше |
|---|---|---|
| Ключи API | Межсерверный доступ из вашего аккаунта | Аутентификация API |
| Модели | Публичные идентификаторы моделей и сведения о готовности | Модели API |
| Генерации | Асинхронные задачи изображений, видео и аудио | Создание генерации |
| Files | Загрузки референсных изображений, видео или аудио | Files API |
| Chat | Ходы чата с потоковой передачей или без нее | Chat API |
| Вебхуки | Подписанные события завершения задач генерации, когда функция включена | API-вебхуки |
Документация API является источником истины для форм запросов и ответов. Эта статья помогает решить, с какой частью начать.
Как работают кредиты
Использование API расходует тот же кредитный кошелек аккаунта Rivya, что и Studio.
Это означает, что API не является анонимным посредником для моделей. Запрос принадлежит аккаунту Rivya, использует созданный этим аккаунтом ключ API и расходует тот же баланс кредитов, который описан в разделе «Кредиты API».
Это удобно для команд: эксперименты в Studio и использование API остаются в одной операционной модели. Модель можно проверить вручную, а затем перенести повторяемую часть в интеграцию без отдельной системы оплаты.
Как вписываются файлы
Некоторые модели могут работать только от текста. Другим нужен референсный файл изображения, видео или аудио.
Для API-интеграций такие референсы должны проходить через Files API. Загрузка создает управляемую запись файла, которую можно передать в поддерживаемые параметры модели.
Практическое правило простое:
если модель принимает только текст, начните с конечной точки генерации
если модели нужны материалы-референсы, сначала загрузите файл
если чат-модели нужны вложенные изображения, используйте Chat API и идентификаторы файлов
Не стройте интеграцию вокруг загрузок, доступных только в браузере, или сохраненных сеансов Studio. API намеренно предоставляет собственный публичный интерфейс для файлов.
Где помогают вебхуки
Polling — самый простой первый путь интеграции. Отправьте задачу генерации, сохраните публичный ID задачи и опрашивайте статус, пока она не завершится успешно или с ошибкой.
Когда вебхуки включены в развертывании, они становятся полезны по мере приближения интеграции к производственной:
вы не хотите, чтобы worker опрашивал каждую задачу
вашему приложению нужно обновить запись после завершения генерации
вам нужно подписанное событие, которое можно безопасно повторить
для неудачных задач должен быть понятный путь восстановления
Контракт подписанных событий описан в API-вебхуках. До проектирования с опорой на них убедитесь, что функция доступна. Ограничьте задачу обработчика вебхуков: проверяйте подписи, обрабатывайте повторные события и не записывайте секреты в логи.
Хороший первый API-проект
Лучший первый API-проект обычно маленький и конкретный.
Например:
убедитесь, что доступ к API включен для развертывания и аккаунта
создайте API-ключ в настройках
запросите список моделей
выберите одну модель, готовую к API
отправьте одну задачу генерации с ключом идемпотентности
опрашивайте конечную точку статуса
проверьте кредиты до и после
только затем добавляйте Files API, Chat API или вебхуки, доступные в развертывании
Такой путь дает рабочую интеграцию без смешивания всех API-возможностей в первом тесте.
Когда API - неправильная отправная точка
API, вероятно, не является правильным первым шагом, когда:
команда еще не выбрала семейство моделей
желаемый результат меняется в каждом запуске
промпт зависит от ручного вкуса и проверки
интеграция скрыла бы расход кредитов от людей, которым нужно его понимать
продукту нужна публичная demo-версия раньше, чем автоматизация
В таких случаях начните с Image, Video, Audio, Chat или AI Models. Когда путь станет повторяемым, перенесите стабильную часть в API.
Куда идти дальше
Откройте Developers, чтобы перейти к публичному разделу API и отладчику.
Прочитайте Быстрый старт Rivya API, чтобы сделать первый безопасный запрос.
Прочитайте Аутентификация API, прежде чем размещать key на сервере.
Прочитайте Модели API, прежде чем выбирать model IDs.
Прочитайте Когда использовать Rivya API вместо Studio, если продуктовая граница все еще неясна.
Прочитайте Как построить мультимодальный процесс ИИ с Rivya API, если вы планируете полную интеграцию изображений, видео, аудио или чата.
