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.
| Bloco de construção | O que ele cuida | Onde ler a seguir |
|---|---|---|
| Chaves de API | Acesso server-to-server a partir da sua conta | Autenticação da API |
| Modelos | IDs públicos de modelo e informações de prontidão | Modelos da API |
| Gerações | Jobs assíncronos de imagem, vídeo e áudio | Criar Geração |
| Arquivos | Uploads de imagem, vídeo ou áudio de referência | Files API |
| Chat | Turnos de chat sem streaming ou com streaming | Chat API |
| Webhooks | Eventos assinados de conclusão para jobs de geração | Webhooks da API |
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:
- crie uma chave de API nas configurações
- chame a lista de modelos
- escolha um modelo disponível
- envie um job de geração com uma chave de idempotência
- faça polling do endpoint de status
- confira créditos antes e depois
- 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.
