Самая простая ошибка - воспринимать Rivya API и Rivya Studio как конкурирующие пути.
Их лучше понимать как две стадии одного продукта. Studio - место, где люди исследуют, выбирают, проверяют и визуально продолжают работу. API - место, где стабильный рабочий процесс становится частью другого продукта, скрипта или backend-процесса.
Если вы еще изучаете API-поверхность, начните с Что такое Rivya API?. Эта страница уже: как решить, должна ли конкретная задача оставаться в Studio или перейти в API.
Решение в одной таблице
| Вопрос | Используйте Studio, когда... | Используйте API, когда... |
|---|---|---|
| Результат все еще исследовательский? | да | нет, рабочий процесс уже повторяемый |
| Нужно ли человеку сравнивать результаты? | да | только после того, как приложение получит результаты |
| Выбор модели стабилен? | еще нет | да, или модель выбирается из списка API-моделей |
| Нужны ли задаче референсные медиа? | человек все еще готовит их | ваше приложение может загрузить их через Files API |
| Должен ли результат обновить другую систему? | пока нет | да, через polling или webhooks |
| Нужно ли сохранять прозрачность расхода кредитов? | да, во время тестирования | да, но через API-контроли уровня аккаунта |
Это не вопрос о том, какая рабочая поверхность более продвинутая. Вопрос в том, готова ли задача к автоматизации.
Используйте Studio, пока работа еще меняется
Studio - правильное место, когда человеческое решение все еще является основной работой.
Это включает:
- выбор между моделями изображений, видео, аудио или чата
- проверку, стоит ли сохранять направление промпта
- сравнение визуальных результатов рядом
- решение, помогает ли референсное медиа или мешает
- использование сохраненной истории для продолжения с предыдущего результата
Это особенно верно для творческой работы. Если бриф нестабилен, автоматизация запроса обычно ускоряет путаницу, а не уменьшает ее.
Используйте API, когда рабочий процесс повторяемый
API становится лучшим путем, когда входные данные и следующие шаги достаточно предсказуемы.
Хорошие признаки:
- ваш продукт уже знает нужную модель или категорию моделей
- пользовательский ввод можно сопоставить со стабильным request body
- backend-задача может опрашивать статус без человека перед экраном
- webhook может обновить правильную запись после завершения задачи
- приложение может объяснить расход кредитов команде или владельцу аккаунта
В этот момент использование Studio для каждого запуска может стать более медленным путем. API позволяет вашему продукту запускать задачу напрямую.
Практичная граница: discovery и integration
Используйте Studio для discovery.
Используйте API для integration.
Discovery означает:
- «Какую модель нам использовать?»
- «Какая форма промпта работает?»
- «Улучшает ли референсное медиа эту задачу?»
- «Достаточно ли качество вывода для этого use case?»
Integration означает:
- «Это действие пользователя должно создать одну задачу генерации.»
- «Эта задача должна повторяться идемпотентно.»
- «Этот файл должен быть загружен и прикреплен к запросу модели.»
- «Эта завершенная задача должна обновить запись в нашем продукте.»
Эта граница не дает API превратиться в скрытую экспериментальную поверхность.
Как кредиты должны влиять на решение
И Studio, и API расходуют одни и те же кредиты аккаунта Rivya.
Это значит, что поведение кредитов должно быть частью продуктового дизайна, а не поздним дополнением.
Сначала используйте Studio, когда команде еще нужно понять форму затрат. Используйте API, когда задача достаточно стабильна, чтобы продукт мог объяснить, когда кредиты могут быть зарезервированы или списаны.
Актуальные публичные правила смотрите в Кредиты API. Если рабочий процесс слишком дорог, чтобы объяснить его владельцу аккаунта, он еще не готов к API-автоматизации.
Где файлы меняют выбор
Референсное медиа часто является местом, где интеграция становится серьезнее.
В Studio человек может загрузить, осмотреть, повторить попытку и решить, достаточно ли хорош файл. В API ваш продукт должен намеренно обрабатывать путь файла через Files API.
Используйте Studio, когда:
- референсное изображение, видео или аудио все еще требует человеческой очистки
- команда не уверена, какой референс должен направлять модель
- правила работы с файлами еще не ясны пользователю
Используйте API, когда:
- приложение может безопасно собрать файл
- требования модели к референсам известны
- файл можно загрузить до запроса генерации или чата
- ошибки можно показать в вашем продукте, не скрывая произошедшее
Files API - полезный мост, но он не отменяет необходимости проектировать файловый опыт.
Где Chat меняет выбор
Chat может принадлежать любой стороне.
Используйте Rivya Chat напрямую, когда человек исследует, пишет, проверяет или принимает решение.
Используйте Chat API, когда ход чата должен жить внутри вашего продукта или серверного процесса. Это может включать non-streaming ходы, опциональный SSE streaming, sessions, созданные через API, и поддерживаемые файловые вложения.
Ключевой вопрос - где должен жить разговор. Если разговор является частью работы в Rivya, используйте Rivya. Если разговор является частью опыта вашего продукта, используйте API.
Когда Webhooks являются сигналом
Если вашему рабочему процессу нужны API-вебхуки, он, вероятно, уже прошел ручную стадию Studio.
Webhooks полезны, когда другая система должна реагировать на завершенные задачи генерации:
- отметить материал как готовый
- уведомить пользователя
- продвинуть шаг проверки
- отправить неудачную задачу в поддержку или логику повтора
Это интеграционная работа. Studio все еще может быть полезна для тестирования пути модели, но production-loop должен жить в API.
Безопасный паттерн миграции
Не переносите весь рабочий процесс в API сразу.
Используйте такую последовательность:
- протестируйте задачу вручную в Studio
- запишите стабильную модель, форму промпта, входные файлы и ожидаемый результат
- прочитайте Модели API и справку по модели
- отправьте одну генерацию через Быстрый старт Rivya API
- добавляйте Files API только если модель требует референсное медиа
- добавляйте Webhooks только после того, как polling работает
- добавляйте Chat API только если продукту нужны ходы чата вне Studio
Каждый шаг должен делать рабочий процесс проще в эксплуатации, а не просто более автоматизированным.
Когда оставаться в Studio
Оставайтесь в Studio, когда задаче все еще нужны:
- субъективная проверка
- формирование промпта
- визуальное сравнение
- исследование моделей
- сохраненная творческая история
- человек, решающий, будет ли следующим шагом изображение, видео, аудио или чат
Это не слабость. Studio спроектирована для этой стадии.
Когда переходить в API
Переходите в API, когда:
- одна и та же задача часто повторяется
- входные данные можно структурировать
- модель известна
- приложению нужно создавать задачи из собственного UI
- статус, ошибки и кредиты можно обрабатывать ясно
- polling или webhooks подходят backend вашего продукта
API сильнее всего тогда, когда превращает уже понятный рабочий процесс Rivya в надежное действие продукта.
Следующий шаг в Rivya
- Используйте Developers, чтобы предварительно посмотреть API-поверхность.
- Прочитайте Быстрый старт Rivya API, прежде чем писать production-код.
- Прочитайте Аутентификация API, прежде чем хранить API key.
- Прочитайте Как построить мультимодальный AI-процесс с Rivya API, если следующий вопрос - как соединить модели, файлы, чат и webhooks.
- Используйте Перенос работы между Rivya Chat, Image, Video, Audio, если проект все еще относится к Studio-работе под руководством человека.
