Создайте мультимодальный рабочий процесс с Rivya API

Хорошая интеграция Rivya API — это не один запрос к одной модели.

Большинство реальных продуктовых процессов образуют небольшую цепочку: выбрать подходящую модель, подготовить исходные данные, при необходимости загрузить референсные файлы, отправить задачу, отслеживать ее состояние, учитывать кредиты и уведомить продукт о готовности результата.

Эта статья показывает, как спланировать такую цепочку. Кратчайший рабочий путь приведен в быстром старте Rivya API, а точные поля запросов — в документации API.

Начните с продуктового момента

Перед выбором эндпоинтов опишите продуктовый сценарий одним предложением.

Примеры:

• Создать черновик изображения продукта, когда продавец отправляет бриф для карточки товара.
• Сгенерировать короткую видеоконцепцию после утверждения направления статичного изображения руководителем кампании.
• Отправить сообщение чата из внутреннего исследовательского инструмента и передавать ответ пользователю потоком.
• Загрузить референсное изображение, отправить запрос поддерживаемой модели и уведомить пользователя о готовности результата.

Такое предложение не дает интеграции превратиться в произвольный набор вызовов API.

Нарисуйте рабочий процесс до написания кода

Используйте эту таблицу до изучения схемы запроса.

Процесс должен быть достаточно ясным, чтобы каждый раздел API использовался по определенной причине.

Шаг 1: создайте ключ для интеграции

Создайте API-ключ для конкретного приложения, окружения или процесса, который будет его использовать.

Не используйте один ключ для всего. Имена по назначению упрощают последующую проверку:

• production-image-workflow
• staging-video-tests
• internal-chat-assistant
• webhook-smoke-test

До сохранения ключа прочитайте раздел «Аутентификация API». Полный секрет показывается один раз, поэтому команда должна сразу поместить его в подходящее серверное хранилище секретов.

Шаг 2: выбирайте модели из публичного списка API

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

Используйте разделы «Модели API» и «Справочник моделей API», чтобы подтвердить:

• публичный ID модели
• доступна ли модель через API
• поддерживаемый режим входных данных
• требования к промпту и параметрам
• требуется ли Files API
• правила списания кредитов и примечания о готовности

На этом этапе многие интеграции становятся понятнее. Модель, идеально подходящая для ручного теста в Studio, может оказаться не лучшим первым выбором для автоматизированного продуктового процесса.

Шаг 3: решите, входит ли Files API в первую версию

Если модель может работать с текстовыми данными, оставьте первую версию только текстовой.

Добавляйте Files API, только когда процесс действительно требует референсных медиафайлов.

Когда это нужно, определите:

• какие типы файлов принимает продукт
• кто отвечает за подготовку файлов
• что происходит при ошибке загрузки
• как данные загруженного файла передаются в параметры модели
• должен ли тот же файл переиспользоваться или загружаться заново

Так хрупкий процесс работы с файлами не будет скрыт за аккуратной кнопкой генерации.

Шаг 4: отправьте одну задачу генерации

Для генерации изображений, видео и аудио обычно используется такая схема:

1. подготовьте ID модели, промпт и поддерживаемые параметры
2. добавьте ключ идемпотентности для безопасных повторов
3. отправьте запрос через эндпоинт генерации
4. сохраните публичный ID задачи
5. опрашивайте состояние, пока задача не перейдет в конечное состояние

Используйте Создание генерации для формы запроса и Статус генерации для обработки результата.

Продукт должен отображать queued, processing, succeeded и failed как понятные пользователю состояния. Не заставляйте людей разбираться в системных деталях или гадать, почему задача выполняется медленно.

Шаг 5: используйте Chat API для чат-моделей

Чат-модели должны использовать Chat API, а не эндпоинт генерации.

Это важно, потому что работа с чатом устроена иначе:

• сообщения чата могут относиться к сессиям, созданным через API
• обычные ответы и потоковая передача SSE создают разный пользовательский опыт
• вложения изображений используют ID файлов из Files API
• окончательное списание кредитов связано с сообщением чата, а не с обычной асинхронной медиазадачей

Если продукту нужен ответ ассистента в собственном интерфейсе, Chat API может быть правильным выбором. Если пользователь все еще исследует идеи, лучше могут подойти Rivya Chat или Studio.

Шаг 6: начните с опроса состояния, затем добавьте вебхуки

Для первой версии опрос состояния проще реализовать и проверить.

Добавляйте API-вебхуки, когда:

• у продукта много асинхронных задач
• ожидающие клиенты не должны напрямую опрашивать состояние
• зависимым системам нужны подписанные события завершения
• обработка повторов и дубликатов уже спроектирована

Обработчики вебхуков должны быть простыми и строгими: проверять подпись, безопасно принимать повторные события, обновлять одну запись продукта и журналировать только безопасные данные.

Шаг 7: сделайте кредиты заметными в продукте

Rivya API использует те же кредиты аккаунта, что и Studio.

Ваша интеграция должна решить, какую часть этого показывать. Как минимум команда должна знать:

• какому аккаунту принадлежит API-ключ
• какой процесс может расходовать кредиты
• что происходит при нехватке кредитов
• как объясняются состояния неудачной генерации
• куда направить пользователя с вопросами о кредитах и биллинге

Для понятного пользователю описания кошелька используйте разделы «Кредиты API», «Rivya: руководство по кредитам и биллингу» и «Кредиты, пакеты и планы Rivya: как это работает».

Маленькая первая версия

Хорошая первая версия намеренно ограничена.

Например:

1. один API-ключ
2. одна выбранная модель изображений
3. без загрузки файлов на первом этапе
4. один запрос генерации
5. один путь опроса состояния
6. простой предварительный просмотр результата в продукте
7. одно ясное сообщение об ошибке кредитов

Такая версия подтверждает работоспособность соединения до добавления новых компонентов.

Более полная версия

После запуска первой версии более полный процесс может включать:

• Files API для референсных изображений или видео
• элементы управления параметрами конкретной модели
• идемпотентность, связанную с записью продукта
• подписанные вебхуки для событий завершения
• Chat API для сообщений ассистента
• серверный поток событий, когда чату нужен вывод в реальном времени
• представления для администраторов или поддержки по неудачным задачам

Каждое дополнение должно отвечать реальной потребности продукта. Если оно лишь увеличивает демонстрационную версию, отложите его.

Частые ошибки интеграции

Избегайте таких подходов:

• начинать сразу со всех возможностей API
• скрывать расход кредитов от владельца аккаунта
• переносить в API допущения, применимые только к Studio
• считать загрузку файлов второстепенной деталью
• повторять запросы генерации без идемпотентности
• использовать Chat API для задач, которые должны быть асинхронной генерацией
• использовать эндпоинты генерации для сообщений чата
• журналировать полные API-ключи, секреты вебхуков или сведения о временных файлах

Самый безопасный процесс API явно определяет владельца, состояния и обработку ошибок.

Куда идти дальше

• Начните со страницы Developers, чтобы открыть публичный центр API.
• Используйте быстрый старт Rivya API, чтобы выполнить первый запрос.
• Изучите модели API до выбора ID моделей.
• Используйте Files API, только когда модели действительно нужны референсные медиафайлы.
• Используйте Chat API для сообщений чата и потоковых ответов.
• Используйте API-вебхуки, когда опроса состояния уже недостаточно.
• Если процесс все еще требует человеческого исследования, перед автоматизацией прочитайте «Когда использовать Rivya API вместо Studio».