Rivya API Quickstart: Generation and Chat
Create an API key, check model availability and credits, submit an image job, poll its status, and start a chat with Rivya Public API v1.
Last reviewed on November 5, 2026
Follow these steps to make your first image generation request and chat turn with Rivya Public API v1.
Use placeholder keys in docs and examples. Never paste a real API key into public code, screenshots, tickets, or shared documents.
Generation and chat requests require a valid account API key, sufficient credits, and a currently callable model. A listed model can be unavailable or require reference files, so check its API status and input requirements before submitting. Deployment settings can temporarily disable API access.
1. Create An API Key
Sign in and open API Keys settings. Create a key, review its permissions, and copy the full secret while it is displayed. Store it in your server-side environment; the full key is shown only once.
The following scopes cover the operations in this guide. Check your key's permissions before calling an endpoint:
models:readgenerations:creategenerations:readfiles:createfiles:readcredits:readwebhooks:managechat:createchat:read
2. Confirm Your Base URL
Use this base URL for requests to Rivya:
https://rivya.aiUse localhost URLs only when developing against your own local instance. Keep real keys out of public examples.
3. List Models
curl https://rivya.ai/api/v1/modelsThis endpoint is public and does not require an API key. Use a model's id as the model value in your request. Check api_status, api_input_status, supported inputs, and parameters: appearing in the catalog does not mean a model can currently accept your request.
4. Check Credits
curl https://rivya.ai/api/v1/credits \
-H "Authorization: Bearer rvya_sk_..."Check your account balance before sending a live request. API calls and Studio use the same credit wallet; live generation can consume credits.
5. Submit A Generation
curl https://rivya.ai/api/v1/generations \
-H "Authorization: Bearer rvya_sk_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quickstart-001" \
-d '{
"model": "z-image",
"prompt": "A clean editorial product image on a soft studio background"
}'Save the public task id from the response. Generation runs asynchronously; an accepted request is not a completed result. Use the same Idempotency-Key when retrying this request, and use a new key for a different request.
6. Poll Status
curl https://rivya.ai/api/v1/generations/task_public_id \
-H "Authorization: Bearer rvya_sk_..."Replace task_public_id with the returned task ID. The public status values are:
queuedprocessingsucceededfailed
Continue checking while the task is queued or processing. A failed status request doesn't mean the generation failed. Check the original task before submitting another job. Read Generation Status for result and error fields.
7. Optional: Add Webhooks
To receive generation status updates on your server, create a webhook endpoint that accepts signed HTTPS callbacks. The deployment must have webhook access enabled, and your key needs webhooks:manage:
curl https://rivya.ai/api/v1/webhooks \
-H "Authorization: Bearer rvya_sk_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Production webhook",
"url": "https://example.com/rivya/webhook",
"event_types": ["generation.succeeded", "generation.failed"]
}'Store the signing_secret when it is returned; it is shown only once. Verify every delivery before trusting its payload. Read API Webhooks for signature verification and delivery handling.
8. Optional: Send A Chat Turn
For a currently callable chat model, send a turn to Chat API. Chat requests use a separate endpoint from asynchronous generation:
curl https://rivya.ai/api/v1/chat/completions \
-H "Authorization: Bearer rvya_sk_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quickstart-chat-001" \
-d '{
"model": "claude-sonnet-5-chat",
"message": "Write a concise launch plan for a new product image campaign"
}'Use the returned session_id to continue this API-created session. For a chat model that accepts images, attachments must reference Files API file_id values. See Chat API for attachment requirements and optional SSE streaming.
Optional: Use The TypeScript SDK Beta
If you have access to the private beta TypeScript SDK source, run the client on your server and keep the secret API key in a server-side environment:
import { RivyaClient } from "@rivya/sdk";
const rivya = new RivyaClient({
apiKey: process.env.RIVYA_API_KEY
});
const generation = await rivya.generations.create({
model: "z-image",
prompt: "A clean editorial product image on a soft studio background"
});The SDK has not been published to npm. If you do not have access to its source, use the HTTP examples above. Read Rivya TypeScript SDK for details about the beta client and server-side Chat streaming.
