Rivya API - це шлях для розробників, які хочуть використовувати можливості моделей Rivya зі свого продукту, скрипта або робочого процесу.
Це не окремий продукт від Rivya Studio. Він використовує ту саму межу акаунта, той самий кредитний гаманець і той самий публічний шар моделей, який користувачі бачать у Rivya. Різниця в тому, як починається робота: замість кліків у Studio ваш застосунок надсилає запити з API-ключем.
Якщо вам потрібні деталі кінцевих точок, почніть із Огляду Rivya API і Швидкий старт Rivya API. Ця стаття - пояснення на продуктовому рівні: для чого API, де він доречний і коли він не має бути першим шляхом.
Коротка версія
Rivya API v1 дозволяє акаунту після входу створювати API-ключі й викликати можливості моделей Rivya поза вебінтерфейсом.
Поточна поверхня API включає:
- пошук моделей через API-список моделей
- асинхронні завдання генерації зображень, відео й аудіо
- завантаження через Files API для моделей, яким потрібні референсні медіа
- опитування статусу генерації з публічними task IDs
- перевірки кредитів акаунта
- ходи Chat API, включно з опційною потоковою передачею SSE
- підписані webhooks для завершення генерації
- бета-версія TypeScript SDK для команд, яким потрібна клієнтська обгортка
Публічний центр для розробників - Developers. Це найкраща точка входу, якщо вам потрібен керований огляд, посилання на налаштування API-ключів і безпечний потік налагодження.
Чому Rivya має API
Studio корисна, коли людина все ще обирає моделі, формує промпти, перевіряє результати й вирішує, що робити далі.
API корисний, коли це рішення перетворилося на повторюваний продуктовий або операційний робочий процес.
Поширені приклади:
- продукт хоче генерувати варіації зображень після того, як користувач надсилає бриф
- маркетинговому робочому процесу потрібно створювати візуальні чернетки зі структурованих вхідних даних кампанії
- внутрішньому інструменту потрібно надсилати відео- або аудіозавдання, не змушуючи когось відкривати браузер
- система підтримки або контенту хоче хід chat-моделі всередині власного інтерфейсу
- бекенд-сервіс хоче підписані зворотні виклики, коли завдання генерації завершуються
У цих випадках Rivya API залишає роботу прив'язаною до того самого акаунта Rivya замість того, щоб змушувати створювати окремий стек для білінгу, вибору моделей і статусу завдань.
Що API не замінює
API не замінює кожну причину використовувати Rivya напряму.
Використовуйте Посібник Rivya Studio або публічні робочі поверхні, коли:
- промпт усе ще потребує людського дослідження
- вибір моделі нестабільний
- автору потрібно візуально порівняти результати
- проєкт залежить від збереженої історії та ручної перевірки
- команда ще не вирішила, який формат вхідних даних і результату має стати повторюваним
Використовуйте API, коли робочий процес достатньо ясний для автоматизації.
Ця межа важлива. Розмите креативне питання зазвичай спершу належить до Studio. Відомий продуктовий потік із передбачуваними вхідними даними може перейти до API.
Основні будівельні блоки
Думайте про API як про шість пов'язаних частин.
| Будівельний блок | Що він обробляє | Де читати далі |
|---|---|---|
| API-ключі | Доступ сервер-до-сервера з вашого акаунта | Автентифікація API |
| Моделі | Публічні ідентифікатори моделей і інформація про готовність | API-моделі |
| Generations | Асинхронні завдання зображень, відео й аудіо | Створення генерації |
| Files | Завантаження референсних зображень, відео або аудіо | Files API |
| Chat | Ходи чату без потокової передачі або з нею | Chat API |
| Webhooks | Підписані події завершення для завдань генерації | API Webhooks |
API-документація є джерелом для форми запитів і відповідей. Ця стаття має допомогти вам вирішити, яка частина потрібна першою.
Як працюють кредити
Використання API списується з того самого кредитного гаманця акаунта Rivya, що й Studio.
Це означає, що API не є анонімним проксі моделей. Запит належить до акаунта Rivya, використовує API-ключ, створений цим акаунтом, і дотримується тієї самої продуктової межі кредитів, описаної в API кредити.
Це корисно для команд, бо експерименти в Studio й використання API залишаються в одній операційній моделі. Ви можете вручну протестувати модель, а потім перенести повторювану частину в інтеграцію без створення другого білінгового шару.
Як вписуються файли
Деякі моделі можуть працювати лише з текстом. Іншим потрібне референсне зображення, відео або аудіофайл.
Для API-інтеграцій ці референси мають проходити через Files API. Завантаження створює керований файловий запис, який можна передати в підтримувані параметри моделі.
Практичне правило просте:
- якщо модель приймає лише текстові вхідні дані, почніть з кінцевої точки генерації
- якщо моделі потрібні референсні медіа, спершу завантажте файл
- якщо модель є чат-моделлю з вкладеннями зображень, використовуйте Chat API і ідентифікатори файлів
Не проєктуйте інтеграцію навколо потоків завантаження лише для браузера або збережених сесій Studio. API має власну публічну файлову межу не випадково.
Де допомагають webhooks
Опитування - найпростіший перший шлях інтеграції. Надішліть завдання генерації, збережіть публічний task ID і опитуйте, доки воно не завершиться успішно або невдало.
Webhooks стають корисними, коли інтеграція більше схожа на production:
- ви не хочете, щоб воркер опитував кожне завдання
- ваш застосунок має оновити запис після завершення генерації
- вам потрібна підписана подія, яку можна безпечно повторити
- невдалі завдання мають переходити в чіткий шлях відновлення
Для контракту підписаних подій використовуйте API Webhooks. Тримайте приймач webhook вузьким: перевіряйте підписи, обробляйте дублікати подій і не записуйте секретні значення в логи.
Хороший перший API-проєкт
Найкращий перший API-проєкт зазвичай малий і конкретний.
Наприклад:
- створіть API-ключ у налаштуваннях
- викличте список моделей
- оберіть одну доступну модель
- надішліть одне завдання генерації з ключем ідемпотентності
- опитайте кінцеву точку статусу
- перевірте кредити до й після
- лише потім додайте Files API, Chat API або Webhooks
Цей шлях дає робочу інтеграцію без змішування кожної API-функції в першому тесті.
Коли API є неправильним стартом
API, ймовірно, не є правильним першим кроком, коли:
- команда ще не обрала сім'ю моделей
- бажаний результат змінюється кожного запуску
- промпт залежить від ручного смаку й перевірки
- інтеграція приховувала б використання кредитів від людей, яким потрібно його розуміти
- продукту потрібна публічна демоверсія раніше, ніж автоматизація
У цих випадках починайте з Image, Video, Audio, Chat або AI Models. Коли шлях стане повторюваним, перенесіть стабільну частину в API.
Куди перейти далі
- Відкрийте Developers для публічного API-хаба й debugger.
- Прочитайте Швидкий старт Rivya API, щоб зробити перший безпечний запит.
- Прочитайте Автентифікація API, перш ніж розміщувати ключ на сервері.
- Прочитайте API-моделі, перш ніж обирати ідентифікатори моделей.
- Прочитайте Коли використовувати Rivya API замість Studio, якщо продуктова межа досі нечітка.
- Прочитайте Як побудувати мультимодальний AI-робочий процес із Rivya API, коли плануєте повну інтеграцію зображень, відео, аудіо або чату.
