Rivya API - это путь для разработчиков, который позволяет использовать возможности моделей Rivya из вашего продукта, скрипта или workflow.
Это не отдельный от Rivya Studio продукт. Он использует ту же границу аккаунта, тот же кредитный кошелек и тот же публичный слой моделей, который пользователи видят в Rivya. Разница в том, как начинается работа: вместо кликов в Studio ваше приложение отправляет запросы с API key.
Если нужны детали endpoints, начните с Обзор Rivya API и Быстрый старт Rivya API. Эта статья объясняет продуктовый уровень: для чего нужен API, где он уместен и когда он не должен быть первым путем.
Короткая версия
Rivya API v1 позволяет авторизованному аккаунту создавать API keys и вызывать возможности моделей Rivya вне web-интерфейса.
Текущая API-поверхность включает:
- discovery моделей через список API-моделей
- асинхронные задачи генерации изображений, видео и аудио
- загрузки через Files API для моделей, которым нужны референсные медиа
- polling статуса генерации по публичным task IDs
- проверки кредитов аккаунта
- ходы Chat API, включая опциональный SSE streaming
- подписанные webhooks для завершения генерации
- TypeScript SDK beta для команд, которым нужен client wrapper
Публичный developer hub - Developers. Это лучший вход, если нужен направляемый обзор, ссылки на настройки API key и безопасный поток отладки.
Зачем Rivya нужен API
Studio полезна, когда человек все еще выбирает модели, формирует промпты, проверяет результаты и решает, что делать дальше.
API полезен, когда это решение превратилось в повторяемый продуктовый или операционный workflow.
Распространенные примеры:
- продукт хочет генерировать варианты изображений после того, как пользователь отправил бриф
- маркетинговый workflow должен создавать визуальные черновики из структурированных campaign-входных данных
- внутреннему инструменту нужно отправлять задачи видео или аудио без просьбы открыть браузер
- система поддержки или content-система хочет ход chat-модели внутри собственного интерфейса
- backend-сервис хочет получать подписанные callbacks после завершения задач генерации
В таких случаях Rivya API сохраняет работу внутри того же аккаунта Rivya, вместо того чтобы заставлять команду строить отдельный стек для биллинга, выбора модели и статуса задач.
Что API не заменяет
API не заменяет все причины использовать Rivya напрямую.
Используйте Руководство Rivya Studio или публичные рабочие поверхности, когда:
- промпт все еще требует человеческого исследования
- выбор модели нестабилен
- автор должен визуально сравнивать результаты
- проект зависит от сохраненной истории и ручной проверки
- команда еще не решила, какой формат входа и выхода должен стать повторяемым
Используйте API, когда workflow достаточно ясен для автоматизации.
Эта граница важна. Расплывчатый творческий вопрос обычно сначала принадлежит Studio. Известный продуктовый поток с предсказуемыми входными данными может перейти в API.
Основные строительные блоки
Думайте об API как о шести связанных частях.
| Блок | За что отвечает | Что читать дальше |
|---|---|---|
| API keys | Server-to-server доступ из вашего аккаунта | Аутентификация API |
| Models | Публичные model IDs и информация о готовности | Модели API |
| Generations | Async задачи изображений, видео и аудио | Создание генерации |
| Files | Загрузки референсных изображений, видео или аудио | Files API |
| Chat | Non-streaming или streaming chat turns | Chat API |
| Webhooks | Подписанные completion events для задач генерации | API-вебхуки |
API-документация является источником истины для формы request и response. Эта статья должна помочь решить, какая часть нужна первой.
Как работают кредиты
Использование API расходует тот же кредитный кошелек аккаунта Rivya, что и Studio.
Это значит, что API - не анонимный model proxy. Запрос принадлежит аккаунту Rivya, использует API key, созданный этим аккаунтом, и следует той же продуктовой границе кредитов, описанной в Кредиты API.
Это полезно для команд, потому что Studio-эксперименты и API-использование остаются в одной операционной модели. Можно протестировать модель вручную, затем перенести повторяемую часть в интеграцию без создания второго слоя биллинга.
Как вписываются файлы
Некоторые модели могут работать только от текста. Другим нужен референсный файл изображения, видео или аудио.
Для API-интеграций такие референсы должны проходить через Files API. Загрузка создает управляемую запись файла, которую можно передать в поддерживаемые параметры модели.
Практическое правило простое:
- если модель принимает text-only вход, начните с generation endpoint
- если модели нужны reference media, сначала загрузите файл
- если chat-модели нужны image attachments, используйте Chat API и file IDs
Не проектируйте интеграцию вокруг upload flows, доступных только в браузере, или сохраненных Studio sessions. У API есть собственная публичная файловая граница не случайно.
Где помогают Webhooks
Polling - самый простой первый путь интеграции. Отправьте задачу генерации, сохраните публичный task ID и опрашивайте статус, пока она не завершится успешно или с ошибкой.
Webhooks становятся полезными, когда интеграция больше похожа на production:
- вы не хотите, чтобы worker опрашивал каждую задачу
- вашему приложению нужно обновить запись после завершения генерации
- вам нужно подписанное событие, которое можно безопасно повторить
- неудачные задачи должны переходить в понятный recovery path
Для контракта подписанного события используйте API-вебхуки. Держите webhook receiver узким: проверяйте signatures, обрабатывайте дублирующиеся events и не пишите secret values в logs.
Хороший первый API-проект
Лучший первый API-проект обычно маленький и конкретный.
Например:
- создайте API key в settings
- вызовите список моделей
- выберите одну доступную модель
- отправьте одну задачу генерации с idempotency key
- опросите endpoint статуса
- проверьте кредиты до и после
- только потом добавляйте Files API, Chat API или Webhooks
Такой путь дает рабочую интеграцию без смешивания всех API-возможностей в первом тесте.
Когда API - неправильная отправная точка
API, вероятно, не является правильным первым шагом, когда:
- команда еще не выбрала семейство моделей
- желаемый результат меняется в каждом запуске
- промпт зависит от ручного вкуса и проверки
- интеграция скрыла бы расход кредитов от людей, которым нужно его понимать
- продукту нужна публичная demo-версия раньше, чем автоматизация
В таких случаях начните с Image, Video, Audio, Chat или AI Models. Когда путь станет повторяемым, перенесите стабильную часть в API.
Куда идти дальше
- Откройте Developers для публичного API hub и debugger.
- Прочитайте Быстрый старт Rivya API, чтобы сделать первый безопасный запрос.
- Прочитайте Аутентификация API, прежде чем размещать key на сервере.
- Прочитайте Модели API, прежде чем выбирать model IDs.
- Прочитайте Когда использовать Rivya API вместо Studio, если продуктовая граница все еще неясна.
- Прочитайте Как построить мультимодальный AI-workflow с Rivya API, если вы планируете полную интеграцию изображений, видео, аудио или чата.
