When to Use Rivya API Instead of Studio

The easiest mistake is treating Rivya API and Rivya Studio as competing paths.

They are better understood as two stages of the same product. Studio is where people explore, choose, review, and continue work visually. The API is where a stable workflow becomes part of another product, script, or backend process.

If you are still learning the API surface, start with What Is the Rivya API?. This page is narrower: how to decide whether a specific task belongs in Studio or in the API.

The Decision In One Table

This is not about which surface is more advanced. It is about whether the task is ready to be automated.

Use Studio While The Work Is Still Changing

Studio is the right place when the human decision is still the main work.

That includes:

• choosing between image, video, audio, or chat models
• testing whether a prompt direction is worth keeping
• comparing visual results side by side
• deciding whether reference media is helping or hurting
• using saved history to continue from a previous result

This is especially true for creative work. If the brief is not stable, automating the request usually makes the confusion faster rather than smaller.

Use The API When The Workflow Is Repeatable

The API becomes the better path when the inputs and next steps are predictable enough.

Good signs:

• your product already knows the model or model category it needs
• user input can be mapped into a stable request body
• a backend job can poll status without someone watching a screen
• a webhook can update the right record when a task finishes
• the app can explain credit usage to the team or account owner

At that point, using Studio for every run can become the slower path. The API lets your product start the task directly.

A Practical Boundary: Discovery Versus Integration

Use Studio for discovery.

Use the API for integration.

Discovery means:

• "Which model should we use?"
• "What prompt shape works?"
• "Does reference media improve this task?"
• "Is the output quality good enough for this use case?"

Integration means:

• "This user action should create one generation job."
• "This job should be retried idempotently."
• "This file should be uploaded and attached to a model request."
• "This completed task should update our product record."

That boundary keeps the API from becoming a hidden experiment surface.

How Credits Should Influence The Decision

Both Studio and API usage draw from the same Rivya account credits.

That means credit behavior should be part of the product design, not an afterthought.

Use Studio first when the team still needs to learn the cost shape. Use the API when the task is stable enough that the product can explain when credits may be reserved or consumed.

For the current public rules, read API Credits. If a workflow is too expensive to explain to the account owner, it is not ready for API automation yet.

Where Files Change The Choice

Reference media is often where an integration becomes more serious.

In Studio, a person can upload, inspect, retry, and decide whether the file is good enough. In the API, your product needs to handle the file path deliberately through Files API.

Use Studio when:

• the reference image, video, or audio still needs human cleanup
• the team is unsure which reference should guide the model
• the file rules are not yet clear to the user

Use the API when:

• the app can collect the file safely
• the model's reference requirements are known
• the file can be uploaded before the generation or chat request
• errors can be shown in your own product without hiding what happened

Files API is a useful bridge, but it does not remove the need to design the file experience.

Where Chat Changes The Choice

Chat can belong on either side.

Use Rivya Chat directly when a person is exploring, writing, reviewing, or deciding.

Use Chat API when the chat turn needs to live inside your own product or server workflow. That can include non-streaming turns, optional SSE streaming, API-created sessions, and supported file attachments.

The key question is where the conversation should live. If the conversation is part of Rivya work, use Rivya. If the conversation is part of your product experience, use the API.

When Webhooks Are A Signal

If your workflow needs API Webhooks, it is probably past the manual Studio stage.

Webhooks are useful when another system needs to respond to completed generation tasks:

• mark an asset as ready
• notify a user
• move a review step forward
• move a failed task into support or retry logic

That is integration work. Studio can still be useful for testing the model path, but the production loop belongs in the API.

A Safe Migration Pattern

Do not move a whole workflow into the API at once.

Use this sequence:

1. test the task manually in Studio
2. write down the stable model, prompt shape, input files, and expected result
3. read API Models and the model reference
4. submit one generation through API Quickstart
5. add Files API only if the model requires reference media
6. add Webhooks only after polling is working
7. add Chat API only if the product needs chat turns outside Studio

Each step should make the workflow easier to operate, not just more automated.

When To Stay In Studio

Stay in Studio when the task still needs:

• subjective review
• prompt shaping
• visual comparison
• model exploration
• saved creative history
• a person deciding whether the next step is image, video, audio, or chat

That is not a weakness. Studio is designed for that stage.

When To Move To API

Move to API when:

• the same task repeats often
• the input can be structured
• the model is known
• the app needs to create tasks from its own UI
• status, errors, and credits can be handled clearly
• polling or webhooks fit the product's backend

The API is strongest when it turns an already-understood Rivya workflow into a reliable product action.

Next Step In Rivya

• Use Developers to preview the API surface.
• Read Rivya API Quickstart before writing production code.
• Read API Authentication before storing an API key.
• Read How to Build a Multimodal AI Workflow with Rivya API if the next question is how to connect models, files, chat, and webhooks.
• Use Moving Work Across Rivya Chat, Image, Video, Audio if the project still belongs in human-led Studio work.