OpenAPI and Schema Contract
Review Rivya API v1 schema sources, compatibility rules, public fields, and the read-only OpenAPI JSON contract.
Last reviewed on August 26, 2026
Rivya API v1 exposes a read-only schema contract at:
https://rivya.ai/api/v1/openapi.jsonThis route is a public contract output. It does not read user session data, does not submit model jobs, and does not expose private account data.
Contract Sources
The contract is derived from:
public API request schemas
public error codes
the public API model reference layer
the same model catalog used by
/api/v1/models
The model list is dynamic. Do not build integrations that depend on a manually written model count.
Version Policy
The current API version is v1.
Backward-compatible changes may include:
adding a model to
/api/v1/modelsadding an optional response field
adding an optional request parameter for a model
adding a new public error code
Breaking changes require a new version or a documented migration path.
Public Field Boundary
Public schema fields use public names:
idstatusmodelsession_idmessageusagereserved_creditsfinal_creditscreated_atupdated_atresulterror
Do not depend on internal task storage fields. They are not part of the public contract.
Request Schema
POST /api/v1/generations accepts:
model: required public model IDprompt: optional string, required by many modelsparams: optional object with model-specific parametersclient_request_id: optional string for your own trace ID
Use Model API Reference for model-specific params.
Reference media returned by /api/v1/files belongs inside params.referenceMediaItems. The schema documents url, kind, optional name, optional mimeType, optional durationSeconds / durationToken, optional width / height / sizeBytes / imageDimensionsToken, and optional framesPerSecond / videoBitrateMbps / videoMetadataToken. Every Image5, Grok Imagine Image 2.0, and Wan 3.0 reference image requires the signed image token and bound byte size from the original model-bound upload response; Layer Decomposition also enforces its documented geometry limits. Every Video8 and Wan 3.0 reference video requires the signed duration token and signed video metadata from the original model-bound upload response. Rivya does not accept a top-level files field in POST /api/v1/generations.
POST /api/v1/files accepts multipart form data with file, kind, optional model, and optional client_request_id. The response is PublicApiFile, including size_bytes, nullable image dimensions, image_dimensions_token, nullable video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, and video_metadata_token. GET /api/v1/files/{fileId} returns public metadata for files owned by the API account, but a signed metadata token that was not persisted may be null and must be replaced by re-uploading.
video_metadata_token is bound to the API account, target model, URL, MIME type, dimensions, frame rate, bitrate, and upload byte size. It does not replace duration_token; Video8 and Wan 3.0 reference videos that use both contracts must provide both tokens. Wan 3.0 audio duration tokens also bind MIME type and upload byte size.
For wan-3-0-video, params accepts only seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed, and referenceMediaItems. Text, frames, and reference scenes are mutually exclusive. Intelligent duration is -1, reserves 30 seconds, and is invalid with reference video; arbitrary keys, unsigned media, file-to-video shortcuts, and link-to-video shortcuts fail closed.
POST /api/v1/chat/completions accepts model, message, optional session_id, optional controls, optional Files API file_id attachments, and optional client_request_id. It returns one complete non-streaming assistant message.
POST /api/v1/chat/completions/stream accepts the same request schema and returns text/event-stream with session.created, message.delta, message.completed, usage.completed, heartbeat, error, and done events. Chat API v1 does not accept a raw messages array.
Response Schemas
The OpenAPI output documents these public response shapes:
ModelListforGET /api/v1/modelsPublicApiModelandModelParamfor model selection and parameter formsPublicApiFileforPOST /api/v1/filesandGET /api/v1/files/{fileId}ReferenceMediaItemfor file-backed generation parametersPublicGenerationfor create and status responsesGenerationResultandGenerationErrorfor completed tasksChatCompletionRequest,ChatCompletion,ChatSession,ChatMessage,ChatUsage,ChatCredits, and Chat stream event schemas for Chat APICreditBalanceforGET /api/v1/creditsWebhookEndpoint,WebhookEvent,WebhookDelivery, andWebhookTestResultfor signed API webhooksPublicApiErrorfor stable error responses
The schema is safe to use for client validation and internal integration tests. The TypeScript SDK beta stays constrained by this schema.
Example Governance
curl, JavaScript, and Python examples in these docs use the same public field names as the schema:
Authorization: Bearer rvya_sk_...Idempotency-Keymodelpromptmessagesession_idparamsclient_request_id
Chat examples additionally use:
chat:createchat:readfile_id
Webhook examples additionally use:
Rivya-Webhook-SignatureRivya-Webhook-Timestampwebhooks:manage
When a model parameter changes, update the model catalog and public serializer first. The docs and debugger should consume that same public layer instead of copying a separate table.