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

В большинстве реальных продуктовых workflow есть небольшая цепочка: выбрать правильную модель, подготовить input, загрузить reference files при необходимости, отправить job, отслеживать status, обработать credits и уведомить продукт, когда результат готов.

Эта статья показывает форму планирования. Для самого короткого запускаемого пути используйте Быстрый старт Rivya API, а точные поля запросов смотрите в API docs.

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

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

Примеры:

Создать черновик продуктового изображения, когда продавец отправляет listing brief.
Сгенерировать короткую видео-концепцию после того, как campaign manager утвердит направление still.
Отправить chat turn внутри внутреннего исследовательского инструмента и stream response обратно пользователю.
Загрузить reference image, отправить supported model request и уведомить пользователя, когда результат готов.

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

Нарисуйте workflow до написания кода

Используйте эту таблицу до открытия request schema.

Workflow step	Продуктовый вопрос	API area
Account access	Какой аккаунт Rivya владеет usage?	Аутентификация API
Model choice	Какой public model ID подходит этой задаче?	Модели API
Reference input	Нужна ли модели uploaded media?	Files API
Generation	Это async image, video или audio job?	Создание генерации
Chat	Это turn chat model, а не generation job?	Chat API
Status	Как продукт узнает, что результат готов?	Статус генерации
Completion event	Должна ли другая система получить signed callback?	API-вебхуки
Credits	Как команда поймет cost?	Кредиты API

Workflow должен быть достаточно ясным, чтобы у каждой API area была причина существовать.

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

Создайте API key для конкретного app, environment или workflow, который будет его использовать.

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

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

Прочитайте Аутентификация API до сохранения key. Полный secret показывается один раз, поэтому команда должна сразу сохранить его в правильное server-side secret store.

Шаг 2: выбирайте модели из public API list

Не hard-code модель только потому, что она сработала в ручном тесте.

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

public model ID
доступна ли модель через API
поддерживаемый input mode
ожидания по prompt и parameters
требуется ли Files API
credit behavior и readiness notes

Именно здесь многие интеграции становятся чище. Модель, идеально подходящая для ручного Studio test, может не быть правильной первой моделью для автоматизированного product flow.

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

Если модель может работать от text input, держите первую версию text-only.

Добавляйте Files API только тогда, когда workflow действительно нуждается в reference media.

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

какие file kinds принимает продукт
кто владеет шагом file cleanup
что происходит, когда upload fails
как returned file data передается в model parameters
должен ли тот же файл переиспользоваться или загружаться заново

Так хрупкий file experience не будет скрыт за аккуратной на вид кнопкой generate.

Шаг 4: отправьте один generation job

Для image, video и audio generation обычный pattern такой:

подготовьте model ID, prompt и supported params
добавьте idempotency key для безопасных retries
отправьте через generation endpoint
сохраните public task ID
poll status, пока task не достигнет terminal state

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

Продукт должен относиться к queued, processing, succeeded и failed как к user-facing states. Не заставляйте пользователей читать системные детали или угадывать, почему job идет медленно.

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

Chat models должны использовать Chat API, а не generation endpoint.

Это важно, потому что у chat work другое поведение:

chat turns могут принадлежать API-created sessions
non-streaming и SSE streaming дают разный user experience
image attachments используют file IDs из Files API
credit settlement следует за chat turn, а не за обычной async media task

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

Шаг 6: начните с polling, затем добавьте webhooks

Для первой версии polling проще осмыслить.

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

у продукта много async jobs
waiting clients не должны напрямую poll
downstream systems нужны signed completion events
retry и duplicate handling уже спроектированы

Webhook receivers должны быть скучными и строгими: verify signature, принимать duplicate-safe events, обновлять одну product record и логировать только то, что безопасно логировать.

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

Rivya API использует те же account credits, что и Studio.

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

какой account владеет API key
какой workflow может потреблять credits
что происходит, когда credits слишком мало
как объясняются failed generation states
куда отправить пользователя с вопросами о credits и billing

Для user-facing wallet model используйте Кредиты API, Rivya: руководство по кредитам и биллингу и Как понимать кредиты, packs и планы Rivya.

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

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

Например:

один API key
одна выбранная image model
пока без file upload
один generation request
один status polling path
один простой result preview в вашем продукте
одно ясное credit error message

Такая версия доказывает соединение до добавления новых moving parts.

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

После того как первая версия заработает, более полный workflow может добавить:

Files API для reference images или videos
элементы управления параметрами конкретной модели
idempotency, связанную с вашей product record
signed webhooks для completion
Chat API для assistant turns
server-side event stream там, где chat needs live output
admin или support views для failed jobs

Каждое добавление должно отвечать на реальную product need. Если оно только делает demo больше, оставьте его в стороне.

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

Избегайте таких pattern:

начинать сразу со всех API features
скрывать credit usage от account owner
использовать Studio-only assumptions в API flow
относиться к file uploads как к второстепенной детали
retry generation requests без idempotency
использовать Chat API для jobs, которые должны быть async generation
использовать generation endpoints для chat turns
логировать полные API keys, webhook secrets или temporary file details

Самый безопасный API workflow явно описывает ownership, state и failure handling.

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

Начните с Developers, чтобы открыть public API hub.
Используйте Быстрый старт Rivya API, чтобы выполнить первый request.
Используйте Модели API до выбора model IDs.
Используйте Files API только когда модели действительно нужна reference media.
Используйте Chat API для chat turns и streaming chat responses.
Используйте API-вебхуки, когда polling уже недостаточно.
Если workflow все еще требует человеческого исследования, прочитайте Когда использовать Rivya API вместо Studio перед автоматизацией.

Соберите мультимодальный workflow с Rivya API