Переглядайте джерела схеми Rivya API v1, правила сумісності, публічні поля та read-only контракт OpenAPI JSON.

Rivya API v1 відкриває read-only контракт схеми за адресою:

https://rivya.ai/api/v1/openapi.json

Цей маршрут є публічним виходом контракту. Він не читає дані сесії користувача, не надсилає задачі моделей і не розкриває приватні дані акаунта.

Джерела контракту

Контракт формується з:

публічних schemas запитів API
публічних кодів помилок
публічного шару API model reference
того самого каталогу моделей, який використовує /api/v1/models

Список моделей є динамічним. Не будуйте інтеграції, які залежать від вручну записаної кількості моделей.

Політика версій

Поточна версія API - v1.

Зворотно сумісні зміни можуть включати:

додавання моделі до /api/v1/models
додавання необов'язкового поля відповіді
додавання необов'язкового параметра запиту для моделі
додавання нового публічного коду помилки

Несумісні зміни потребують нової версії або задокументованого шляху міграції.

Межа публічних полів

Публічні поля схеми використовують публічні назви:

id
status
model
session_id
message
usage
reserved_credits
final_credits
created_at
updated_at
result
error

Не покладайтеся на внутрішні поля зберігання задач. Вони не є частиною публічного контракту.

Схема запиту

POST /api/v1/generations приймає:

model: обов'язковий публічний ID моделі
prompt: необов'язковий рядок, потрібний багатьом моделям
params: необов'язковий об'єкт із параметрами, специфічними для моделі
client_request_id: необов'язковий рядок для вашого trace ID

Використовуйте Model API Reference для params, специфічних для моделі.

Референс-медіа, повернені /api/v1/files, мають бути всередині params.referenceMediaItems. Схема документує url, kind, необов'язкові name і mimeType, необов'язкові durationSeconds / durationToken, необов'язкові width / height / sizeBytes / imageDimensionsToken, а також необов'язкові framesPerSecond / videoBitrateMbps / videoMetadataToken. Кожне референс-зображення для Image5, Grok Imagine Image 2.0 або Wan 3.0 потребує підписаного токена зображення та прив'язаного розміру в байтах із початкової відповіді завантаження, прив'язаної до моделі; Layer Decomposition також застосовує задокументовані геометричні обмеження. Кожне референс-відео Video8 і Wan 3.0 потребує підписаного токена тривалості та підписаних відеометаданих із початкової відповіді завантаження, прив'язаної до моделі. Rivya не приймає поле верхнього рівня files у POST /api/v1/generations.

POST /api/v1/files приймає multipart form data з file, kind, необов'язковим model і необов'язковим client_request_id. Відповідь має форму PublicApiFile, включно з size_bytes, nullable-розмірами зображення, image_dimensions_token, nullable-полями video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes і video_metadata_token. GET /api/v1/files/{fileId} повертає публічні метадані файлів, що належать API-акаунту, але підписаний токен метаданих, який не було збережено, може мати значення null; у такому разі його потрібно замінити повторним завантаженням файлу.

video_metadata_token прив'язаний до API-акаунту, цільової моделі, URL, MIME-типу, розмірів, частоти кадрів, бітрейту й розміру завантаження в байтах. Він не замінює duration_token: відеореференси Video8 і Wan 3.0, які використовують обидва контракти, мають надавати обидва токени. Токени тривалості аудіо Wan 3.0 також прив'язуються до MIME-типу й розміру завантаження в байтах.

Для wan-3-0-video об'єкт params приймає лише seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed і referenceMediaItems. Режими тексту, кадрів і референсів взаємовиключні. Розумна тривалість має значення -1, резервує 30 секунд і несумісна з референс-відео; довільні поля, непідписані медіа та спрощені режими file-to-video або link-to-video відхиляються без переходу до запасного сценарію.

POST /api/v1/chat/completions приймає model, message, необов'язковий session_id, необов'язкові керування, необов'язкові вкладення file_id через Files API і необов'язковий client_request_id. Він повертає одне повне повідомлення асистента без потокового передавання.

POST /api/v1/chat/completions/stream приймає ту саму схему запиту й повертає text/event-stream з подіями session.created, message.delta, message.completed, usage.completed, heartbeat, error і done. Chat API v1 не приймає сирий масив messages.

Схеми відповідей

OpenAPI output документує такі публічні форми відповідей:

ModelList для GET /api/v1/models
PublicApiModel і ModelParam для вибору моделей і форм параметрів
PublicApiFile для POST /api/v1/files і GET /api/v1/files/{fileId}
ReferenceMediaItem для параметрів генерації з файловими референсами
PublicGeneration для відповідей створення й перевірки статусу
GenerationResult і GenerationError для завершених задач
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits і схеми подій stream Chat для Chat API
CreditBalance для GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery і WebhookTestResult для підписаних API webhooks
PublicApiError для стабільних відповідей з помилками

Схему безпечно використовувати для клієнтської валідації та внутрішніх інтеграційних тестів. TypeScript SDK beta лишається обмеженим цією схемою.

Керування прикладами

Приклади curl, JavaScript і Python у цих docs використовують ті самі публічні назви полів, що й схема:

Authorization: Bearer rvya_sk_...
Idempotency-Key
model
prompt
message
session_id
params
client_request_id

Chat-приклади додатково використовують:

chat:create
chat:read
file_id

Webhook-приклади додатково використовують:

Rivya-Webhook-Signature
Rivya-Webhook-Timestamp
webhooks:manage

Коли параметр моделі змінюється, спочатку оновіть каталог моделей і публічний серіалізатор. Docs і debugger мають використовувати той самий публічний шар, а не копіювати окрему таблицю.

OpenAPI і контракт схеми