↓
Documentação da Rivya AI

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:read

  • generations:create

  • generations:read

  • files:create

  • files:read

  • credits:read

  • webhooks:manage

  • chat:create

  • chat:read

2. Confirmar sua Base URL

Use a base URL da API de produção:

https://rivya.ai

URLs 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/models

Use 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:

  • queued

  • processing

  • succeeded

  • failed

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.

Próximas Páginas