Quando Usar a Rivya API em Vez do Studio

O erro mais fácil é tratar Rivya API e Rivya Studio como caminhos concorrentes.

É melhor entendê-los como duas etapas do mesmo produto. Studio é onde pessoas exploram, escolhem, revisam e continuam o trabalho visualmente. A API é onde um workflow estável se torna parte de outro produto, script ou processo de backend.

Se você ainda está aprendendo a superfície da API, comece por O que é a Rivya API?. Esta página é mais estreita: como decidir se uma tarefa específica pertence ao Studio ou à API.

A decisão em uma tabela

Isto não é sobre qual superfície é mais avançada. É sobre se a tarefa está pronta para ser automatizada.

Use Studio enquanto o trabalho ainda está mudando

Studio é o lugar certo quando a decisão humana ainda é o trabalho principal.

Isso inclui:

• escolher entre modelos de imagem, vídeo, áudio ou chat
• testar se uma direção de prompt vale manter
• comparar resultados visuais lado a lado
• decidir se a mídia de referência está ajudando ou atrapalhando
• usar histórico salvo para continuar a partir de um resultado anterior

Isso é especialmente verdadeiro para trabalho criativo. Se o briefing não está estável, automatizar a solicitação normalmente torna a confusão mais rápida, não menor.

Use a API quando o workflow é repetível

A API se torna o melhor caminho quando os inputs e os próximos passos são previsíveis o bastante.

Bons sinais:

• seu produto já sabe qual modelo ou categoria de modelo precisa
• o input do usuário pode ser mapeado para um corpo de solicitação estável
• um job de backend pode fazer polling de status sem alguém observando uma tela
• um webhook pode atualizar o registro certo quando uma tarefa termina
• o app consegue explicar o uso de créditos para a equipe ou dona da conta

Nesse ponto, usar Studio para cada execução pode virar o caminho mais lento. A API permite que seu produto inicie a tarefa diretamente.

Um limite prático: descoberta versus integração

Use Studio para descoberta.

Use a API para integração.

Descoberta significa:

• "Qual modelo devemos usar?"
• "Que formato de prompt funciona?"
• "Mídia de referência melhora esta tarefa?"
• "A qualidade do output é boa o bastante para este caso de uso?"

Integração significa:

• "Esta ação do usuário deve criar um job de geração."
• "Este job deve ser tentado novamente de forma idempotente."
• "Este arquivo deve ser enviado e anexado a uma solicitação de modelo."
• "Esta tarefa concluída deve atualizar nosso registro de produto."

Esse limite impede que a API vire uma superfície oculta de experimentação.

Como os créditos devem influenciar a decisão

Tanto o uso do Studio quanto o uso da API consomem os mesmos créditos da conta Rivya.

Isso significa que o comportamento de créditos deve fazer parte do design do produto, não ser uma reflexão posterior.

Use Studio primeiro quando a equipe ainda precisa aprender o formato de custo. Use a API quando a tarefa estiver estável o bastante para que o produto consiga explicar quando créditos podem ser reservados ou consumidos.

Para as regras públicas atuais, leia Créditos da API. Se um workflow é caro demais para explicar à dona da conta, ele ainda não está pronto para automação por API.

Onde arquivos mudam a escolha

Mídia de referência muitas vezes é onde uma integração fica mais séria.

No Studio, uma pessoa pode enviar, inspecionar, tentar novamente e decidir se o arquivo é bom o bastante. Na API, seu produto precisa lidar deliberadamente com o caminho do arquivo pela Files API.

Use Studio quando:

• a imagem, vídeo ou áudio de referência ainda precisa de limpeza humana
• a equipe não tem certeza de qual referência deve guiar o modelo
• as regras de arquivo ainda não estão claras para o usuário

Use a API quando:

• o app consegue coletar o arquivo com segurança
• os requisitos de referência do modelo são conhecidos
• o arquivo pode ser enviado antes da solicitação de geração ou chat
• erros podem ser mostrados no seu próprio produto sem esconder o que aconteceu

Files API é uma ponte útil, mas não remove a necessidade de desenhar a experiência de arquivos.

Onde chat muda a escolha

Chat pode pertencer aos dois lados.

Use Rivya Chat diretamente quando uma pessoa está explorando, escrevendo, revisando ou decidindo.

Use Chat API quando o turno de chat precisa viver dentro do seu próprio produto ou workflow de servidor. Isso pode incluir turnos sem streaming, streaming SSE opcional, sessões criadas pela API e anexos de arquivo suportados.

A pergunta principal é onde a conversa deve viver. Se a conversa faz parte do trabalho na Rivya, use a Rivya. Se a conversa faz parte da experiência do seu produto, use a API.

Quando webhooks são um sinal

Se seu workflow precisa de Webhooks da API, provavelmente já passou da etapa manual de Studio.

Webhooks são úteis quando outro sistema precisa responder a tarefas de geração concluídas:

• marcar um asset como pronto
• notificar um usuário
• avançar uma etapa de revisão
• mover uma tarefa com falha para suporte ou lógica de nova tentativa

Isso é trabalho de integração. Studio ainda pode ser útil para testar o caminho do modelo, mas o ciclo de produção pertence à API.

Um padrão seguro de migração

Não mova um workflow inteiro para a API de uma só vez.

Use esta sequência:

1. teste a tarefa manualmente no Studio
2. anote o modelo estável, o formato do prompt, os arquivos de input e o resultado esperado
3. leia Modelos da API e a referência de modelos
4. envie uma geração por Quickstart da API
5. adicione Files API somente se o modelo exigir mídia de referência
6. adicione Webhooks somente depois que polling estiver funcionando
7. adicione Chat API somente se o produto precisar de turnos de chat fora do Studio

Cada etapa deve tornar o workflow mais fácil de operar, não apenas mais automatizado.

Quando permanecer no Studio

Permaneça no Studio quando a tarefa ainda precisa de:

• revisão subjetiva
• modelagem de prompt
• comparação visual
• exploração de modelos
• histórico criativo salvo
• uma pessoa decidindo se o próximo passo é imagem, vídeo, áudio ou chat

Isso não é uma fraqueza. Studio foi desenhado para essa etapa.

Quando mover para API

Mova para API quando:

• a mesma tarefa se repete com frequência
• o input pode ser estruturado
• o modelo é conhecido
• o app precisa criar tarefas a partir da própria UI
• status, erros e créditos podem ser tratados com clareza
• polling ou webhooks combinam com o backend do produto

A API é mais forte quando transforma um fluxo da Rivya já entendido em uma ação confiável de produto.

Próximo passo na Rivya

• Use Developers para pré-visualizar a superfície da API.
• Leia Quickstart da Rivya API antes de escrever código de produção.
• Leia Autenticação da API antes de armazenar uma chave de API.
• Leia Crie um fluxo multimodal com a API da Rivya se a próxima pergunta é como conectar modelos, arquivos, chat e webhooks.
• Use Movendo Trabalho Entre Chat, Image, Video e Audio da Rivya se o projeto ainda pertence a trabalho humano no Studio.