Rivya API v1 OpenAPI schema and compatibility
Read the Rivya API v1 OpenAPI 3.1.0 document. Check request and response shapes, model input requirements, authentication, and compatibility rules.
Last reviewed on November 11, 2026
Use Rivya's OpenAPI document to inspect API v1 request and response shapes before building a client. The schema URL is:
https://rivya.ai/api/v1/openapi.jsonThis endpoint is public and needs no API key. It reads the published model catalog, without reading user sessions or private account records, and does not submit generation jobs.
To save a local copy:
curl --fail https://rivya.ai/api/v1/openapi.json -o rivya-openapi.jsonAuthentication rules in the document apply to the operations it describes. Most operations need a Bearer API key with the appropriate scope; GET /api/v1/models is public. See API key authentication for permissions.
Prompt units and complete layer results
Read prompt_length_unit together with max_prompt_length from GET /api/v1/models. utf8_bytes counts the original text bytes, including spaces and line breaks; utf16_code_units counts JavaScript UTF-16 units. A null limit does not mean unlimited or optional text. Gemini TTS uses the byte unit.
A completed layer-decomposition result can include result.layers alongside the complete result.urls list. Keep each layer’s z_index, URL, size, name, description and bounding box when provided; index zero is the base image. The TypeScript SDK exposes these fields. Upload references for the selected model and pass its original signed metadata; declared dimensions or duration alone do not replace verification.
Contract Sources
The OpenAPI route uses shared public error codes and scopes, along with current model reference records. Its request and response definitions are maintained explicitly and need to stay aligned with:
public API request schemas
public error codes
the public API model reference layer
the same model catalog used by
/api/v1/models
Model IDs and readiness can change. Read api_status, supported inputs, and the model's category before selecting an endpoint. A listed model is not necessarily callable. Use API Models instead of relying on a fixed catalog count.
Version Policy
The document uses openapi: 3.1.0 for its OpenAPI format and info.version: v1 for Rivya's API version. These labels describe different things.
Use tooling that supports OpenAPI 3.1 and its JSON Schema features, including conditional schemas. A generator that targets an earlier format may not preserve those validation rules.
Backward-compatible changes within v1 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
Clients should allow for newly listed models, optional fields, and unfamiliar public error codes. Refresh the schema when reviewing an integration change; an old enum snapshot can reject values added later.
Breaking changes require a new API version or a documented migration path.
Public Field Boundary
The schema uses public field names, including:
idstatusmodelsession_idmessageusagereserved_creditsfinal_creditssettlement_statuscreated_atupdated_atresulterror
Use the public fields in your integration. Internal task storage fields are outside this contract.
A required property can still allow null. For example, PublicApiFile requires the duration_token property in its response shape, but the value may be null. Preserve both field presence and nullability in client types.
Request Schema
POST /api/v1/generations uses these top-level fields:
model: required public model ID. Use an available image, video, or audio model for this endpoint; chat models use Chat API.prompt: optional at the request-shape level. The selected model and mode determine whether it is required and its length limit.params: optional object containing model-specific controls and reference inputs.client_request_id: optional trace ID from your system, up to 128 characters. It does not replaceIdempotency-Key.
Use Model API Reference for model-specific params, and Create Generation for submission examples.
For models that accept uploaded references, put the Files API response data in params.referenceMediaItems. There is no top-level files field in the generation request contract.
The generic ReferenceMediaItem shape requires url and kind. It also defines name, mimeType, durationSeconds, durationToken, width, height, sizeBytes, imageDimensionsToken, framesPerSecond, videoBitrateMbps, and videoMetadataToken as optional properties. A model's input rules can require fields that are optional in this generic shape.
Signed image references for seedream-5-pro, seedream-5-pro-layer-decomposition, nano-banana-2-lite, qwen-image-3, qwen-image-3-pro, Grok Imagine Image 2.0, and Wan 3.0 need the original model-bound upload's image token and byte size. Layer Decomposition also checks its documented image geometry limits.
Reference videos for seedance-2-mini, seedance-2-5, minimax-h3, gemini-omni-video, gemini-omni-flash-1-1, volcengine-video-lip-sync, and wan-3-0-video need signed duration and video metadata from the original model-bound upload. Keep both tokens with the matching original metadata.
POST /api/v1/files accepts multipart form data with required file and kind, plus optional model and client_request_id. For a signed reference, upload with the target model ID so its tokens can be checked against that model.
The PublicApiFile response includes size_bytes, width, height, image_dimensions_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, and video_metadata_token, alongside file identifiers and duration fields. Image and video measurements and signed tokens may be null when unavailable.
GET /api/v1/files/{fileId} returns metadata for an available file owned by the API account. In this response, image dimensions, video measurements, image_dimensions_token, and video_metadata_token are always null. A reissued audio duration_token omits the MIME type and byte size, so it cannot replace the original model-bound upload token for strict audio checks. Keep the original upload response for signed references, and re-upload when required metadata is unavailable or expired. See Files API.
video_metadata_token binds the account, target model, URL, MIME type, dimensions, frame rate, bitrate, and upload byte size. It does not replace duration_token; requests that require both forms of verification must provide both tokens. Wan 3.0 audio duration tokens from the original model-bound POST /api/v1/files upload also bind MIME type and upload byte size.
For wan-3-0-video, the accepted params keys are seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed, and referenceMediaItems. Text, frames, and reference scenes are mutually exclusive. Intelligent duration uses -1 and reserves credits for 30 output seconds; it is unavailable with reference video. Unsupported keys, unsigned media, and file-to-video or link-to-video shortcuts are rejected.
ChatCompletionRequest requires model and message. session_id, controls, Files API file_id attachments, and client_request_id are optional; their use depends on the selected chat model's capabilities. A successful POST /api/v1/chat/completions returns one complete, non-streaming assistant message.
POST /api/v1/chat/completions/stream accepts the same request shape. When a stream starts, it uses text/event-stream and can contain session.created, message.delta, message.completed, usage.completed, heartbeat, error, and done events. Errors before streaming use an HTTP error response. Chat API v1 does not accept a raw messages array. See Chat API for streaming and session rules.
Response Schemas
The document names these response schemas:
ModelListforGET /api/v1/modelsPublicApiModelandModelParamfor model selection and parameter formsPublicApiFileforPOST /api/v1/filesandGET /api/v1/files/{fileId}PublicGenerationfor generation creation and status responsesGenerationResultandGenerationErrorfor a task'sresultanderrorfieldsChatCompletion,ChatSession,ChatMessage,ChatUsage,ChatCredits, and Chat stream event schemas for Chat APICreditBalanceforGET /api/v1/creditsWebhookEndpoint,WebhookEvent,WebhookDelivery, andWebhookTestResultfor signed API webhooksPublicApiErrorfor public HTTP error responses
Use the schema for client validation and integration tests against its documented shapes. Passing those checks does not guarantee that a request can run: the API also checks account permissions, model input combinations, signed upload metadata, and runtime availability. Follow the selected model's requirements and handle errors with API Errors and Limits.
Read generation status separately from settlement_status. A successful task can still need credit settlement, and result.primary_url can be null. See Generation Status and API Credits for those fields.
The Rivya TypeScript SDK wraps Public API v1 using static types. It is a private beta and is not yet published to npm. Its types do not perform full runtime schema validation or make unavailable models callable.
Example Governance
curl, JavaScript, and Python examples in these docs use public request field names and HTTP headers:
Authorization: Bearer rvya_sk_...Idempotency-Keymodelpromptmessagesession_idparamsclient_request_id
Chat examples also use these scopes and attachment fields:
chat:createchat:readfile_id
Webhook examples also use signing headers and a management scope:
Rivya-Webhook-SignatureRivya-Webhook-Timestampwebhooks:manage
Replace key and media placeholders with your own values before running a request. Use the model catalog and public reference for current parameters; copying a separate static table can leave an integration using old values.
For maintainers, a parameter change must be reflected in the model catalog and public serializer, then in the schema, docs, and debugger that use those fields. Review the resulting public shapes together.
Common questions
Do I need an API key to download the OpenAPI document?
No. GET /api/v1/openapi.json is public. Authenticated operations described in the document still need the appropriate key and scopes.
Does passing schema validation mean a generation can run?
No. Check the model's category, api_status, inputs, and parameters, along with your account permissions and available credits. The schema describes fields; the API checks whether the selected operation can run.
