Quickstart da Rivya API
Crie uma chave de API, escolha um modelo, envie uma tarefa assíncrona de geração e faça um turno na Chat API com streaming SSE opcional.
Última revisão em 5 de novembro de 2026
Este quickstart mostra o caminho seguro mais curto desde a configuração da conta até um job de geração da Rivya API, além do primeiro turno da Chat API.
Use chaves placeholder em docs e exemplos. Nunca cole uma chave real de API em código público, capturas de tela, tickets ou documentos compartilhados.
Os exemplos descrevem o contrato implementado da API Pública v1. Antes de testar, confirme que o acesso à API Pública está habilitado no deployment e disponível para a conta. Um endpoint ou página de modelo documentado não prova, por si só, que a requisição executa em todos os ambientes.
1. Criar uma Chave de API
Abra configurações de Chaves de API, crie uma chave, copie o segredo completo uma vez e armazene-o no ambiente do seu servidor.
Novas chaves nas configurações recebem todos os nove escopos abaixo, sem seletor. Não é possível editar permissões de uma chave antiga.
models:readgenerations:creategenerations:readfiles:createfiles:readcredits:readwebhooks:managechat:createchat:read
2. Confirmar sua Base URL
Use a base URL da API de produção:
https://rivya.aiURLs localhost são apenas para desenvolvimento local. Exemplos públicos não devem usar segredos locais.
3. Listar Modelos
A lista de modelos é pública e dispensa chave. Confira api_status: available, preparo da entrada e modo. Estar listado não autoriza execução; modelos de Chat usam o endpoint próprio.
curl https://rivya.ai/api/v1/modelsUse o campo id da resposta como valor de model ao criar uma geração.
4. Verificar Créditos
curl https://rivya.ai/api/v1/credits \
-H "Authorization: Bearer rvya_sk_..."Use isso para confirmar o saldo atual da conta antes ou depois dos testes.
5. Enviar uma Geração
Aceitação não significa conclusão. Envie Idempotency-Key desde a primeira tentativa; ao repetir o pedido, mantenha chave API e corpo. Outra geração usa nova chave de idempotência.
curl https://rivya.ai/api/v1/generations \
-H "Authorization: Bearer rvya_sk_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quickstart-001" \
-d '{
"model": "z-image",
"prompt": "A clean editorial product image on a soft studio background"
}'A resposta retorna um ID público de tarefa. Armazene-o para consultar o status depois.
6. Consultar Status
Com queued ou processing, continue consultando a tarefa original. Erro de consulta não significa falha de geração. Guarde o ID e siga o guia de status para estado e liquidação.
curl https://rivya.ai/api/v1/generations/task_public_id \
-H "Authorization: Bearer rvya_sk_..."Valores de status:
queuedprocessingsucceededfailed
7. Opcional: Adicionar Webhooks
Gerenciar endpoints exige webhooks:manage e o recurso habilitado. Veja entrega, assinatura e inscrições em API Webhooks. Sem confirmação da notificação, consulte a tarefa original.
Se o acesso a webhooks estiver habilitado para o deployment e a conta, e seu servidor puder receber callbacks HTTPS assinados, crie um endpoint de webhook:
curl https://rivya.ai/api/v1/webhooks \
-H "Authorization: Bearer rvya_sk_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Production webhook",
"url": "https://example.com/rivya/webhook",
"event_types": ["generation.succeeded", "generation.failed"]
}'Salve o signing_secret de uso único da resposta e verifique toda entrega antes de confiar no payload.
8. Opcional: Enviar um Turno de Chat
Confira chat_capabilities; use anexos por file_id apenas em modelos que aceitem imagens. Os Claude disponíveis atualmente recebem apenas texto. Veja campos e streaming em Chat API.
Para modelos de chat, chame a Chat API em vez de POST /api/v1/generations:
curl https://rivya.ai/api/v1/chat/completions \
-H "Authorization: Bearer rvya_sk_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quickstart-chat-001" \
-d '{
"model": "claude-sonnet-5-chat",
"message": "Write a concise launch plan for a new product image campaign"
}'Use o session_id retornado para continuar a sessão criada pela API. Anexos de imagem devem referenciar valores file_id da Files API.
Opcional: Usar o Beta do TypeScript SDK
O SDK é beta privado, sem publicação no npm público. É preciso acesso ao código ou pacote compilado e resolução de @rivya/sdk no servidor. Sem esse acesso, use HTTP diretamente.
Integrações TypeScript do lado do servidor podem usar o beta do SDK local:
import { RivyaClient } from "@rivya/sdk";
const rivya = new RivyaClient({
apiKey: process.env.RIVYA_API_KEY
});
const generation = await rivya.generations.create({
model: "z-image",
prompt: "A clean editorial product image on a soft studio background"
});Leia Rivya TypeScript SDK antes de adotá-lo. O SDK inclui suporte a streaming de Chat do lado do servidor no beta privado.
