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.

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.

Escopos iniciais recomendados:

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

curl https://rivya.ai/api/v1/models

Use o campo id da resposta como valor de model ao criar uma geração.

4. Enviar uma Geração

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.

5. Consultar Status

curl https://rivya.ai/api/v1/generations/task_public_id \
  -H "Authorization: Bearer rvya_sk_..."

Valores de status:

queued
processing
succeeded
failed

6. 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.

7. Opcional: Adicionar Webhooks

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

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

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.

Quickstart da Rivya API