Create an API key, choose a model, submit an asynchronous generation job, and send a Chat API turn with optional SSE streaming.

This quickstart shows the shortest safe path from account setup to one Rivya API generation job, plus the first Chat API turn.

Use placeholder keys in docs and examples. Never paste a real API key into public code, screenshots, tickets, or shared documents.

1. Create An API Key

Open API Keys settings, create a key, copy the full secret once, and store it in your server-side environment.

Recommended first scopes:

models:read
generations:create
generations:read
files:create
files:read
credits:read
webhooks:manage
chat:create
chat:read

2. Confirm Your Base URL

Use the production API base URL:

https://rivya.ai

Localhost URLs are only for local development. Public examples should not use local secrets.

3. List Models

curl https://rivya.ai/api/v1/models

Use the id field from the response as the model value when creating a generation.

4. 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"
  }'

The response returns a public task ID. Store it so you can poll status later.

5. Poll Status

curl https://rivya.ai/api/v1/generations/task_public_id \
  -H "Authorization: Bearer rvya_sk_..."

Status values are:

queued
processing
succeeded
failed

6. Check Credits

curl https://rivya.ai/api/v1/credits \
  -H "Authorization: Bearer rvya_sk_..."

Use this to confirm the current account balance before or after testing.

7. Optional: Add Webhooks

If your server can receive signed HTTPS callbacks, create a webhook endpoint:

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"]
  }'

Save the one-time signing_secret from the response and verify every delivery before trusting the payload.

8. Optional: Send A Chat Turn

For chat models, call Chat API instead of POST /api/v1/generations:

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": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign"
  }'

Use the returned session_id to continue the API-created session. Image attachments must reference Files API file_id values.

Optional: Use The TypeScript SDK Beta

Server-side TypeScript integrations can use the local SDK beta:

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"
});

Read Rivya TypeScript SDK before adopting it. The SDK includes server-side Chat streaming support in the private beta.

Rivya API Quickstart