Хороша інтеграція Rivya API - це не просто один запит до однієї моделі.
Більшість реальних продуктових робочих процесів мають невеликий ланцюжок: обрати правильну модель, підготувати ввід, завантажити референсні файли за потреби, надіслати завдання, відстежити статус, обробити кредити й повідомити продукт, коли результат готовий.
Ця стаття показує форму планування. Використовуйте Швидкий старт Rivya API для найкоротшого запускного шляху, а API-документи - для точних полів запиту.
Почніть із продуктового моменту
Перед вибором кінцевих точок опишіть продуктовий момент одним реченням.
Приклади:
Створити чернетку продуктового зображення, коли продавець надсилає listing brief.Згенерувати коротку відеоконцепцію після того, як менеджер кампанії затвердить статичний напрям.Надіслати чат-репліку всередині внутрішнього дослідницького інструмента й передати відповідь назад користувачу потоком.Завантажити референсне зображення, надіслати запит підтримуваної моделі й повідомити користувача, коли результат буде готовий.
Це речення не дає інтеграції перетворитися на розхитану колекцію API-викликів.
Зіставте робочий процес до написання коду
Використовуйте цю таблицю перед відкриттям схеми запиту.
| Крок робочого процесу | Продуктове питання | API-зона |
|---|---|---|
| Доступ до акаунта | Який акаунт Rivya володіє використанням? | Автентифікація API |
| Вибір моделі | Який публічний ID моделі підходить цьому завданню? | API-моделі |
| Референсний ввід | Чи потрібні моделі завантажені медіа? | Files API |
| Генерація | Це асинхронне завдання для зображення, відео або аудіо? | Створення генерації |
| Chat | Це репліка чат-моделі замість завдання генерації? | Chat API |
| Статус | Як продукт дізнається, що результат готовий? | Статус генерації |
| Подія завершення | Чи має інша система отримати підписаний зворотний виклик? | API Webhooks |
| Кредити | Як команда зрозуміє вартість? | API кредити |
Робочий процес має бути достатньо ясним, щоб кожна API-зона мала причину існувати.
Крок 1: створіть ключ для інтеграції
Створіть ключ API для конкретного застосунку, середовища або робочого процесу, який його використовуватиме.
Не використовуйте один ключ для всього. Назви ключів за призначенням полегшують подальшу перевірку:
production-image-workflowstaging-video-testsinternal-chat-assistantwebhook-smoke-test
Прочитайте Автентифікація API перед збереженням ключа. Повний секрет показується один раз, тож команда має одразу зберегти його в правильному серверному сховищі секретів.
Крок 2: обирайте моделі з публічного API-списку
Не прописуйте модель жорстко лише тому, що вона спрацювала в ручному тесті.
Використовуйте API-моделі і Model API Reference, щоб підтвердити:
- публічний ID моделі
- чи доступна модель через API
- підтримуваний режим вводу
- очікування щодо промпта й параметрів
- чи потрібен Files API
- поведінку кредитів і нотатки готовності
Саме тут багато інтеграцій стають чистішими. Модель, ідеальна для ручного Studio-тесту, може не бути правильною першою моделлю для автоматизованого продуктового потоку.
Крок 3: вирішіть, чи Files API входить у першу версію
Якщо модель може працювати з текстового вводу, тримайте першу версію лише текстовою.
Додавайте Files API лише тоді, коли робочому процесу справді потрібні референсні медіа.
Коли це потрібно, визначте:
- які типи файлів приймає продукт
- хто відповідає за крок очищення файлів
- що відбувається, коли завантаження провалюється
- як повернені дані файлу передаються в параметри моделі
- чи той самий файл треба повторно використати або завантажити знову
Це не дає крихкому файловому досвіду сховатися за чистою на вигляд кнопкою генерації.
Крок 4: надішліть одне завдання генерації
Для генерації зображень, відео й аудіо нормальний патерн такий:
- підготувати ID моделі, промпт і підтримувані параметри
- додати idempotency key для безпечних повторних спроб
- надіслати через кінцеву точку генерації
- зберегти публічний ID завдання
- опитувати статус, доки завдання не досягне кінцевого стану
Використовуйте Створення генерації для форми запиту й Статус генерації для обробки результату.
Продукт має трактувати queued, processing, succeeded і failed як стани, видимі користувачу. Не змушуйте користувачів читати системні деталі або здогадуватися, чому завдання повільне.
Крок 5: використовуйте Chat API для чат-моделей
Чат-моделі мають використовувати Chat API, а не кінцеву точку генерації.
Це важливо, бо чат-робота має іншу поведінку:
- чат-репліки можуть належати до сесій, створених API
- режим без потокової передачі й потокова передача SSE мають різний користувацький досвід
- прикріплені зображення використовують ID файлів із Files API
- списання кредитів прив'язане до чат-репліки, а не до звичайного асинхронного медійного завдання
Якщо вашому продукту потрібна відповідь асистента всередині власного інтерфейсу, Chat API може бути правильним шляхом. Якщо користувач усе ще досліджує ідеї, Rivya Chat або Studio можуть бути кращими.
Крок 6: почніть з опитування, потім додайте вебхуки
Для першої версії опитування легше осмислити.
Додавайте API Webhooks, коли:
- продукт має багато асинхронних завдань
- клієнти, що чекають, не мають опитувати напряму
- низхідні системи потребують підписаних подій завершення
- повторні спроби й обробка дублікатів уже спроєктовані
Приймачі вебхуків мають бути нудними й суворими: перевірити підпис, прийняти події, безпечні для дублікатів, оновити один продуктовий запис і логувати лише те, що безпечно логувати.
Крок 7: зробіть кредити видимими в продукті
Rivya API використовує ті самі кредити акаунта, що й Studio.
Ваша інтеграція має вирішити, яку частину цього показувати. Як мінімум команда має знати:
- який акаунт володіє ключем API
- який робочий процес може споживати кредити
- що відбувається, коли кредитів замало
- як пояснюються стани невдалої генерації
- куди відправити людину з питаннями про кредити й білінг
Використовуйте API кредити, Кредити й білінг у Rivya і Як думати про кредити, пакети й плани Rivya для користувацької моделі гаманця.
Мала перша версія
Хороша перша версія навмисно обмежена.
Наприклад:
- один ключ API
- одна вибрана модель зображення
- поки без завантаження файлу
- один запит генерації
- один шлях опитування статусу
- один простий попередній перегляд результату у вашому продукті
- одне зрозуміле повідомлення про помилку кредитів
Ця версія доводить з'єднання перед додаванням більшої кількості рухомих частин.
Повніша версія
Після того як перша версія працює, повніший робочий процес може додати:
- Files API для референсних зображень або відео
- керування параметрами конкретної моделі
- idempotency, прив'язану до продуктового запису
- підписані вебхуки для завершення
- Chat API для реплік асистента
- потік подій на серверному боці там, де чату потрібен живий вихід
- адмінські подання або подання підтримки для невдалих завдань
Кожне додавання має відповідати на реальну продуктову потребу. Якщо воно лише робить демо більшим, залиште його поза межами.
Поширені помилки інтеграції
Уникайте таких патернів:
- стартувати з усіх API-функцій одразу
- приховувати використання кредитів від власника акаунта
- використовувати припущення лише зі Studio в API-потоці
- ставитися до завантаження файлів як до другорядної деталі
- повторювати generation requests без idempotency
- використовувати Chat API для завдань, які мають бути асинхронною генерацією
- використовувати кінцеві точки генерації для чат-реплік
- логувати повні ключі API, секрети вебхуків або тимчасові деталі файлів
Найбезпечніший API-робочий процес явно описує власність, стан і обробку збоїв.
Куди йти далі
- Почніть із Developers як публічного API-хаба.
- Використовуйте Швидкий старт Rivya API, щоб виконати перший запит.
- Використовуйте API-моделі перед вибором ID моделей.
- Використовуйте Files API лише тоді, коли моделі справді потрібні референсні медіа.
- Використовуйте Chat API для чат-реплік і потокових чат-відповідей.
- Використовуйте API Webhooks, коли опитування вже недостатньо.
- Якщо робочому процесу все ще потрібне людське дослідження, прочитайте Коли використовувати Rivya API замість Studio перед автоматизацією.
