Rivya Public API Overview
Connect your app to Rivya API v1 for image, video, audio, and Chat. Check access, model availability, account credits, and the first integration steps.
Last reviewed on November 5, 2026
Rivya API v1 lets your app submit asynchronous image, video, and audio generation tasks and send Chat turns. Submitting these requests requires Public API access to be enabled for the deployment and a valid account API key with the required permissions.
Generation returns public task IDs for status queries. Chat uses API-created sessions and supports complete JSON responses or server-sent events (SSE). Requests use Rivya model IDs and the credit balance of the account that owns the key.
The v1 HTTP endpoints are under https://rivya.ai/api/v1. Start with API Quickstart for request examples.
What The API Is For
Use the API when you want to:
submit image, video, or audio generation jobs from your own app
send non-streaming or streaming chat turns and continue API-created chat sessions
use the same account credit balance for API and Studio requests
poll task status by public task ID
retry supported requests with the same
Idempotency-Key, API key, and unchanged request bodyread generation tasks and API-created Chat sessions owned by your account
Use Rivya model IDs in requests and the documented Public API fields in responses.
Continue API-created Chat sessions with session_id. Chat sessions created in Rivya's web interface cannot be continued through the Chat API.
Current Version Scope
The main v1 endpoints are:
GET /api/v1/modelsPOST /api/v1/generationsPOST /api/v1/filesGET /api/v1/files/{fileId}POST /api/v1/chat/completionsPOST /api/v1/chat/completions/streamGET /api/v1/chat/sessionsGET /api/v1/chat/sessions/{sessionId}GET /api/v1/generations/{taskId}GET /api/v1/creditsGET /api/v1/webhooksPOST /api/v1/webhooksGET /api/v1/webhook-eventsGET /api/v1/openapi.json
See the OpenAPI schema for request and response definitions and the other webhook management routes.
GET /api/v1/models includes unavailable and Coming Soon entries. Choose a model whose api_status is available, then check its runtime, supported inputs, and parameters in the Model API Reference. Provider support for a feature does not mean it is enabled in Rivya.
Signed webhooks cover completion events for API-created asynchronous generation tasks. To manage webhook endpoints, Public API and webhooks must be enabled for the deployment, and your key needs webhooks:manage. Register an active endpoint for the events you need; see API Webhooks for signing and delivery rules.
The TypeScript SDK is a private beta and has not been published to npm. If you have access to its source, use it on your server; otherwise, follow the HTTP examples in API Quickstart. Read Rivya TypeScript SDK for the beta client and server-side streaming.
Authentication
GET /api/v1/models and GET /api/v1/openapi.json are public. The other endpoints require a valid API key with the appropriate permissions. Send this HTTP header:
Authorization: Bearer rvya_sk_...Create keys in API Keys settings. To rotate a key, create a replacement, update your server credentials, and revoke the old key. Read API Authentication for key permissions and access requirements.
Keep secret API keys on your server. Do not put them in browser code or public repositories.
Billing Model
API calls use the same Rivya account credits as Studio.
Generation tasks reserve credits before submission to the model. Chat turns also reserve credits before the model call.
Final credits follow the model's billing rules and reported credit usage. Read the credit fields for the settled charge. GPT-5.2 can settle a complete response from confirmed token counts and its model credit rates when explicit consumption is absent. Credit fields can reflect the reserve while settlement is pending or requires reconciliation; check settlement_status for the settlement result.
Refunds depend on the confirmed task or turn state and its credit settlement rules. A timeout, dropped stream, or failed status query does not mean the task or turn failed or that credits were returned. Check the original task or session before retrying.
Read API Credits and Credits & Billing in Rivya for balances, reserves, final settlement, and refunds.
First Integration Path
Create an API key in Settings.
Call List API Models and choose an available model for the endpoint you need.
Read Model API Reference for the model's parameters, input limits, and required media.
Check your available balance with API Credits before submitting a generation task or Chat turn.
If the model needs reference media, upload it with Files API for that model. Keep the original upload response and pass the signed metadata and fields required by the model.
Submit a job with Create Generation.
Poll Generation Status until the task succeeds or fails. You can also register an active webhook endpoint for signed generation results when Public API and webhooks are enabled. Query status if a notification is missing.
For chat models, use Chat API instead of the generation endpoint and check
chat_capabilities. Image attachments, where supported, must use Files APIfile_idvalues.
Related Pages
Common integration questions
Do I need the SDK to use the API?
No. You can use the HTTP endpoints directly with a server-side API key. The TypeScript SDK is optional and remains a private beta; API Quickstart provides HTTP examples.
Does a timeout mean I should submit again?
A timeout does not confirm that the request failed. Check the original task or Chat session first. If you retry an endpoint that supports idempotency, follow its rules for reusing the same API key, Idempotency-Key, and request body.
