What Is the Rivya API?

The Rivya API is the developer path for using Rivya model capabilities from your own product, script, or workflow.

It is not a separate product from Rivya Studio. It uses the same account boundary, the same credit wallet, and the same public model layer that users see across Rivya. The difference is how the work starts: instead of clicking through Studio, your application sends requests with an API key.

If you need endpoint details, start with Rivya API Overview and Rivya API Quickstart. This article is the product-level explanation: what the API is for, where it fits, and when it should not be the first path.

The Short Version

Rivya API v1 lets a signed-in account create API keys and call Rivya model capabilities from outside the web interface.

The current API surface includes:

• model discovery through the API model list
• asynchronous image, video, and audio generation jobs
• Files API uploads for models that need reference media
• generation status polling with public task IDs
• account credit checks
• Chat API turns, including optional SSE streaming
• signed webhooks for generation completion
• a TypeScript SDK beta for teams that want a client wrapper

The public developer hub is Developers. It is the best entry if you want a guided overview, links to API key settings, and a safe debugger flow.

Why Rivya Has an API

Studio is useful when a person is still choosing models, shaping prompts, reviewing outputs, and deciding what to do next.

The API is useful when that decision has turned into a repeatable product or operational workflow.

Common examples:

• a product wants to generate image variations after a user submits a brief
• a marketing workflow needs to create visual drafts from structured campaign inputs
• an internal tool needs to submit video or audio jobs without asking someone to open the browser
• a support or content system wants a chat model turn inside its own interface
• a backend service wants signed callbacks when generation jobs finish

In those cases, Rivya API keeps the work connected to the same Rivya account instead of forcing a separate stack for billing, model selection, and task status.

What The API Does Not Replace

The API does not replace every reason to use Rivya directly.

Use Studio or the public work surfaces when:

• the prompt still needs human exploration
• the model choice is not stable
• a creator needs to compare outputs visually
• the project depends on saved history and manual review
• the team has not decided which input and output format should become repeatable

Use the API when the workflow is clear enough to automate.

That boundary matters. A vague creative question usually belongs in Studio first. A known product flow with predictable inputs can move to the API.

The Main Building Blocks

Think of the API as six connected pieces.

The API docs are the source for request and response shape. This article should help you decide which piece you need first.

How Credits Work

API usage draws from the same Rivya account credit wallet as Studio.

That means the API is not an anonymous model proxy. A request belongs to a Rivya account, uses an API key created by that account, and follows the same product-level credit boundary described in API Credits.

This is useful for teams because Studio experiments and API usage stay in one operational model. You can test a model manually, then move the repeatable part into an integration without creating a second billing layer.

How Files Fit In

Some models can run from text alone. Others need a reference image, video, or audio file.

For API integrations, those references should go through Files API. The upload creates a managed file record that can be passed into supported model parameters.

The practical rule is simple:

• if a model accepts text-only input, start with the generation endpoint
• if a model needs reference media, upload the file first
• if the model is a chat model with image attachments, use Chat API and file IDs

Do not design your integration around browser-only upload flows or saved Studio sessions. The API has its own public file boundary for a reason.

Where Webhooks Help

Polling is the easiest first integration path. Submit a generation job, save the public task ID, and poll until it succeeds or fails.

Webhooks become useful when the integration is more production-like:

• you do not want a worker polling every job
• your app needs to update a record when generation finishes
• you want a signed event that can be retried safely
• failed jobs need to move into a clear recovery path

For the signed event contract, use API Webhooks. Keep the webhook receiver narrow: verify signatures, handle duplicate events, and avoid putting secret values in logs.

A Good First API Project

The best first API project is usually small and concrete.

For example:

1. create an API key in settings
2. call the model list
3. choose one available model
4. submit one generation job with an idempotency key
5. poll the status endpoint
6. check credits before and after
7. only then add Files API, Chat API, or Webhooks

That path gives you a working integration without mixing every API feature into the first test.

When The API Is The Wrong Starting Point

The API is probably not the right first step when:

• the team has not chosen a model family yet
• the desired output is still changing every run
• the prompt depends on manual taste and review
• the integration would hide credit usage from the people who need to understand it
• the product needs a public demo before it needs automation

In those cases, start from Image, Video, Audio, Chat, or AI Models. Once the path is repeatable, move the stable part to the API.

Where To Go Next

• Open Developers for the public API hub and debugger.
• Read Rivya API Quickstart to make the first safe request.
• Read API Authentication before putting a key on a server.
• Read API Models before choosing model IDs.
• Read When to Use Rivya API Instead of Studio if the product boundary is still unclear.
• Read How to Build a Multimodal AI Workflow with Rivya API when you are planning a full image, video, audio, or chat integration.