O que é a Rivya API?

A Rivya API é o caminho para desenvolvedores usarem capacidades dos modelos Rivya a partir do próprio produto, script ou workflow.

Ela não é um produto separado do Rivya Studio. Usa o mesmo limite de conta, a mesma carteira de créditos e a mesma camada pública de modelos que usuários veem em toda a Rivya. A diferença é como o trabalho começa: em vez de clicar pelo Studio, sua aplicação envia solicitações com uma chave de API.

Se você precisa de detalhes de endpoints, comece por Visão Geral da Rivya API e Quickstart da Rivya API. Este artigo é a explicação no nível do produto: para que serve a API, onde ela se encaixa e quando ela não deve ser o primeiro caminho.

A versão curta

Rivya API v1 permite que uma conta logada crie chaves de API e chame capacidades dos modelos Rivya de fora da interface web.

A superfície atual da API inclui:

• descoberta de modelos pela lista de modelos da API

• jobs assíncronos de geração de imagem, vídeo e áudio

• uploads pela Files API para modelos que precisam de mídia de referência

• polling de status de geração com IDs públicos de tarefa

• verificações de créditos da conta

• turnos da Chat API, incluindo streaming SSE opcional

• webhooks assinados para conclusão de geração

• beta do TypeScript SDK para equipes que querem um wrapper de cliente

O hub público de desenvolvedores é Developers. É a melhor entrada se você quer uma visão guiada, links para configurações de chave de API e um fluxo seguro de debugger.

Por que a Rivya tem uma API

Studio é útil quando uma pessoa ainda está escolhendo modelos, moldando prompts, revisando outputs e decidindo o que fazer em seguida.

A API é útil quando essa decisão virou um produto repetível ou workflow operacional.

Exemplos comuns:

• um produto quer gerar variações de imagem depois que um usuário envia um briefing

• um workflow de marketing precisa criar rascunhos visuais a partir de inputs estruturados de campanha

• uma ferramenta interna precisa enviar jobs de vídeo ou áudio sem pedir que alguém abra o navegador

• um sistema de suporte ou conteúdo quer um turno de modelo de chat dentro da própria interface

• um serviço de backend quer callbacks assinados quando jobs de geração terminam

Nesses casos, a Rivya API mantém o trabalho conectado à mesma conta Rivya em vez de forçar uma stack separada para cobrança, seleção de modelo e status de tarefa.

O que a API não substitui

A API não substitui todos os motivos para usar a Rivya diretamente.

Use Studio ou as superfícies públicas de trabalho quando:

• o prompt ainda precisa de exploração humana

• a escolha de modelo não está estável

• uma pessoa criadora precisa comparar outputs visualmente

• o projeto depende de histórico salvo e revisão manual

• a equipe ainda não decidiu qual formato de input e output deve se tornar repetível

Use a API quando o workflow estiver claro o bastante para automatizar.

Esse limite importa. Uma pergunta criativa vaga geralmente pertence primeiro ao Studio. Um fluxo de produto conhecido com inputs previsíveis pode ir para a API.

Os principais blocos de construção

Pense na API como seis peças conectadas.

Os docs da API são a fonte para o formato de request e response. Este artigo deve ajudar você a decidir qual peça precisa primeiro.

Como os créditos funcionam

O uso da API consome a mesma carteira de créditos da conta Rivya que o Studio.

Isso significa que a API não é um proxy anônimo de modelos. Uma solicitação pertence a uma conta Rivya, usa uma chave de API criada por essa conta e segue o mesmo limite de créditos no nível do produto descrito em Créditos da API.

Isso é útil para equipes porque experimentos no Studio e uso da API permanecem em um único modelo operacional. Você pode testar um modelo manualmente e depois mover a parte repetível para uma integração sem criar uma segunda camada de cobrança.

Como arquivos entram no fluxo

Alguns modelos podem executar apenas a partir de texto. Outros precisam de uma imagem, vídeo ou arquivo de áudio de referência.

Para integrações por API, essas referências devem passar pela Files API. O upload cria um registro de arquivo gerenciado que pode ser passado para parâmetros de modelos suportados.

A regra prática é simples:

• se um modelo aceita input somente de texto, comece pelo endpoint de geração

• se um modelo precisa de mídia de referência, envie o arquivo primeiro

• se o modelo é um modelo de chat com anexos de imagem, use Chat API e IDs de arquivo

Não desenhe sua integração em torno de fluxos de upload exclusivos do navegador ou sessões salvas do Studio. A API tem o próprio limite público de arquivos por um motivo.

Onde webhooks ajudam

Polling é o caminho mais fácil para a primeira integração. Envie um job de geração, salve o ID público da tarefa e faça polling até ter sucesso ou falhar.

Webhooks se tornam úteis quando a integração parece mais com produção:

• você não quer um worker fazendo polling de todo job

• seu app precisa atualizar um registro quando a geração termina

• você quer um evento assinado que possa ser tentado novamente com segurança

• jobs com falha precisam seguir para um caminho claro de recuperação

Para o contrato de evento assinado, use Webhooks da API. Mantenha o receiver de webhook estreito: verifique assinaturas, trate eventos duplicados e evite colocar valores secretos em logs.

Um bom primeiro projeto com API

O melhor primeiro projeto com API costuma ser pequeno e concreto.

Por exemplo:

1. crie uma chave de API nas configurações

2. chame a lista de modelos

3. escolha um modelo disponível

4. envie um job de geração com uma chave de idempotência

5. faça polling do endpoint de status

6. confira créditos antes e depois

7. só então adicione Files API, Chat API ou Webhooks

Esse caminho dá uma integração funcional sem misturar todos os recursos da API no primeiro teste.

Quando a API é o ponto de partida errado

A API provavelmente não é o primeiro passo certo quando:

• a equipe ainda não escolheu uma família de modelo

• o output desejado ainda muda a cada execução

• o prompt depende de gosto e revisão manual

• a integração esconderia uso de créditos das pessoas que precisam entendê-lo

• o produto precisa de uma demo pública antes de precisar de automação

Nesses casos, comece por Image, Video, Audio, Chat ou Modelos de IA. Quando o caminho for repetível, mova a parte estável para a API.

Para onde ir agora

• Abra Developers para o hub público da API e debugger.

• Leia Quickstart da Rivya API para fazer a primeira solicitação segura.

• Leia Autenticação da API antes de colocar uma chave em um servidor.

• Leia Modelos da API antes de escolher IDs de modelo.

• Leia Quando Usar a Rivya API em Vez do Studio se o limite do produto ainda estiver pouco claro.

• Leia Crie um fluxo multimodal com a API da Rivya quando estiver planejando uma integração completa de imagem, vídeo, áudio ou chat.