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

Rivya API v1 предоставляет read-only контракт схемы здесь:

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

Этот route является публичным выводом контракта. Он не читает данные пользовательской session, не отправляет задачи моделей и не раскрывает приватные данные аккаунта.

Источники контракта

Контракт формируется из:

публичных схем запросов API
публичных кодов ошибок
публичного слоя справочника моделей API
того же каталога моделей, который используется /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: необязательная строка для вашего ID трассировки

Модельные params см. в справочнике Model API.

Справочные медиа, возвращенные /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-формы с file, kind, необязательным model и необязательным client_request_id. Ответ — PublicApiFile, включающий size_bytes, размеры изображения, которые могут иметь пустое значение, image_dimensions_token, а также допускающие пустое значение 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 секунд и недопустима со справочным видео; произвольные ключи, неподписанные медиафайлы и быстрые пути преобразования файла в видео или ссылки в видео отклоняются по принципу закрытого отказа.

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 не принимает raw-массив messages.

Схемы ответов

Вывод OpenAPI документирует эти публичные формы ответов:

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 и схемы событий стрима чата для Chat API
CreditBalance для GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery и WebhookTestResult для подписанных API-вебхуков
PublicApiError для стабильных ответов об ошибках

Схему можно безопасно использовать для клиентской валидации и внутренних интеграционных тестов. Бета TypeScript SDK остается ограничена этой схемой.

Управление примерами

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

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

Когда параметр модели меняется, сначала обновите каталог моделей и публичный сериализатор. Документация и отладчик должны использовать тот же публичный слой, а не копировать отдельную таблицу.

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