↓
Rivya AI Docs

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:read

  • generations:create

  • generations:read

  • files:create

  • files:read

  • credits:read

  • webhooks:manage

  • chat:create

  • chat:read

2. Confirm Your Base URL

Use this base URL for requests to Rivya:

https://rivya.ai

Use 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/models

This 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:

  • queued

  • processing

  • succeeded

  • failed

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.

Next Pages