Переглядайте джерела схеми 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. Schema документує url, kind, необов'язковий name, необов'язковий mimeType, необов'язковий durationSeconds і необов'язковий durationToken. Rivya не приймає поле верхнього рівня files у POST /api/v1/generations.

POST /api/v1/files приймає multipart form data з file, kind, необов'язковим model і необов'язковим client_request_id. Відповідь має форму PublicApiFile. GET /api/v1/files/{fileId} повертає ті самі публічні метадані файлу для файлів, що належать API-акаунту.

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 і контракт схеми