Visão Geral da Rivya API
Use a Rivya API v1 para chamar modelos de geração e chat da Rivya a partir do seu próprio produto com chaves de API, créditos da conta e streaming SSE opcional.
Última revisão em 5 de novembro de 2026
A Rivya API v1 é o contrato para desenvolvedores chamarem capacidades compatíveis dos modelos Rivya no próprio produto, quando o acesso à API Pública está habilitado no deployment e disponível para a conta.
O contrato implementado cobre geração assíncrona de imagem, vídeo e áudio, além de turnos da Chat API com respostas sem streaming ou via SSE. Ele usa IDs de modelos Rivya, créditos da conta, IDs públicos de tarefas de geração e sessões de chat no servidor. Uma rota documentada não promete que todo ambiente, conta ou modelo do catálogo possa chamá-la; confirme o acesso ao vivo e a prontidão do modelo antes de integrar.
Para Que Serve a API
Repetições idempotentes mantêm Idempotency-Key, chave API e corpo. É possível ler gerações e sessões API da conta; conversas criadas na interface web não podem continuar pela Chat API. Veja exemplos HTTP no início rápido.
Use a API quando quiser:
enviar jobs de geração de imagem, vídeo ou áudio a partir do seu próprio app
enviar turnos de chat sem streaming ou com streaming e continuar sessões de chat criadas pela API
manter o faturamento dentro da mesma carteira de créditos da conta Rivya
consultar status de tarefa por ID público
usar novas tentativas idempotentes para solicitações de produção mais seguras
manter o uso de Studio e API dentro do mesmo limite de conta
A API é uma camada de produto da Rivya. Respostas públicas usam apenas nomes Rivya e campos públicos.
Escopo da Versão Atual
O OpenAPI contém definições completas e outras rotas de webhook. A lista inclui modelos indisponíveis e Coming Soon; escolha api_status: available e confira runtime, entrada e parâmetros na referência. Suporte do provedor não significa habilitação em Rivya.
Webhooks assinados cobrem gerações assíncronas criadas pela API. Gerenciar endpoints exige API e webhooks habilitados e webhooks:manage na chave da solicitação de gestão. A entrega considera endpoints ativos e inscrições da conta proprietária da tarefa. Veja API Webhooks.
O SDK continua em beta privado e ainda não foi publicado no npm. Quem tiver acesso ao código-fonte pode usá-lo no servidor. Sem acesso, use os exemplos HTTP do início rápido. Veja cliente e streams no SDK TypeScript.
Os endpoints implementados da v1 incluem:
GET /api/v1/modelsPOST /api/v1/generationsPOST /api/v1/filesGET /api/v1/files/{fileId}POST /api/v1/chat/completionsPOST /api/v1/chat/completions/streamGET /api/v1/chat/sessionsGET /api/v1/chat/sessions/{sessionId}GET /api/v1/generations/{taskId}GET /api/v1/creditsGET /api/v1/webhooksPOST /api/v1/webhooksGET /api/v1/webhook-eventsGET /api/v1/openapi.json
O contrato atual inclui webhooks assinados para resultados de geração assíncrona, Chat API e um beta do TypeScript SDK com streaming no servidor. Chamadas de webhook exigem que o recurso de webhooks e o acesso à API Pública estejam habilitados no deployment.
Autenticação
GET /api/v1/models e GET /api/v1/openapi.json são públicos; as outras rotas exigem chave válida e escopos. Guarde o segredo no servidor, fora do navegador e de repositórios públicos.
Endpoints de geração, status e créditos exigem:
Authorization: Bearer rvya_sk_...Crie e rotacione chaves em configurações de Chaves de API. Leia Autenticação da API antes de usar uma chave em produção.
Modelo de Cobrança
API e Studio usam o mesmo saldo, reservando créditos antes da chamada. O valor final segue as regras do modelo e o uso de créditos informado; tokens de Chat não são a cobrança. Enquanto a liquidação estiver pendente, o valor pode refletir a reserva; leia settlement_status.
Devoluções seguem o estado confirmado e as regras. Timeout, corte ou erro de consulta não prova falha nem devolução; confira a tarefa ou sessão original antes de repetir. Veja Créditos da API e créditos e cobrança.
Primeiro Caminho de Integração
Confira disponibilidade no endpoint e preparo da entrada. Guarde a resposta original completa do upload para o modelo e os campos assinados. Sem notificação, consulte a tarefa original. Anexos dependem de chat_capabilities; os Claude atuais aceitam apenas texto.
Crie uma chave de API em Configurações.
Chame Listar Modelos da API para escolher um ID público de modelo.
Leia a Referência da API de Modelos para os parâmetros do modelo.
Confira o saldo em Créditos da API antes de enviar.
Se o modelo precisar de mídia de referência, envie-a com a Files API.
Envie um job com Criar Geração.
Consulte Status de Geração até a tarefa ter sucesso ou falhar. Se webhooks estiverem habilitados para o deployment e a conta, você também pode assinar Webhooks da API para receber eventos assinados de conclusão.
Para modelos de chat, use Chat API em vez do endpoint de geração. Anexos de imagem no Chat devem referenciar valores
file_idda Files API.
Páginas Relacionadas
Dúvidas de integração
Preciso do SDK?
Não. Use HTTP diretamente no servidor com a chave API. O SDK é opcional e continua beta privado; o início rápido traz exemplos HTTP.
Um timeout significa que devo enviar novamente?
Não confirma falha. Confira primeiro a tarefa ou sessão original e, em rotas idempotentes, siga as regras para a mesma chave API, Idempotency-Key e corpo.
