Revise fontes de schema da Rivya API v1, regras de compatibilidade, campos públicos e o contrato JSON OpenAPI somente leitura.

A Rivya API v1 expõe um contrato de schema somente leitura em:

https://rivya.ai/api/v1/openapi.json

Esta rota é uma saída de contrato público. Ela não lê dados de sessão de usuário, não envia jobs de modelo e não expõe dados privados da conta.

Fontes do Contrato

O contrato é derivado de:

schemas públicos de solicitação da API
códigos públicos de erro
a camada pública de referência de modelos da API
o mesmo catálogo de modelos usado por /api/v1/models

A lista de modelos é dinâmica. Não crie integrações que dependam de uma contagem de modelos escrita manualmente.

Política de Versão

A versão atual da API é v1.

Mudanças compatíveis com versões anteriores podem incluir:

adicionar um modelo a /api/v1/models
adicionar um campo opcional de resposta
adicionar um parâmetro opcional de solicitação para um modelo
adicionar um novo código público de erro

Mudanças incompatíveis exigem uma nova versão ou um caminho de migração documentado.

Limite dos Campos Públicos

Campos públicos de schema usam nomes públicos:

id
status
model
session_id
message
usage
reserved_credits
final_credits
created_at
updated_at
result
error

Não dependa de campos internos de armazenamento de tarefas. Eles não fazem parte do contrato público.

Schema de Solicitação

POST /api/v1/generations aceita:

model: ID público obrigatório do modelo
prompt: string opcional, obrigatória em muitos modelos
params: objeto opcional com parâmetros específicos do modelo
client_request_id: string opcional para seu próprio ID de rastreamento

Use a Referência da API de Modelos para params específicos por modelo.

Mídia de referência retornada por /api/v1/files pertence a params.referenceMediaItems. O schema documenta url, kind, name opcional, mimeType opcional, durationSeconds opcional e durationToken opcional. A Rivya não aceita um campo files de nível superior em POST /api/v1/generations.

POST /api/v1/files aceita dados de formulário multipart com file, kind, model opcional e client_request_id opcional. A resposta é PublicApiFile. GET /api/v1/files/{fileId} retorna os mesmos metadados públicos de arquivo para arquivos pertencentes à conta da API.

POST /api/v1/chat/completions aceita model, message, session_id opcional, controles opcionais, anexos opcionais da Files API por file_id e client_request_id opcional. Ele retorna uma mensagem completa de assistente sem streaming.

POST /api/v1/chat/completions/stream aceita o mesmo schema de solicitação e retorna text/event-stream com eventos session.created, message.delta, message.completed, usage.completed, heartbeat, error e done. A Chat API v1 não aceita um array bruto de messages.

Schemas de Resposta

A saída OpenAPI documenta estes formatos públicos de resposta:

ModelList para GET /api/v1/models
PublicApiModel e ModelParam para seleção de modelos e formulários de parâmetros
PublicApiFile para POST /api/v1/files e GET /api/v1/files/{fileId}
ReferenceMediaItem para parâmetros de geração baseados em arquivos
PublicGeneration para respostas de criação e status
GenerationResult e GenerationError para tarefas concluídas
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits e schemas de eventos de stream de Chat para a Chat API
CreditBalance para GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery e WebhookTestResult para webhooks assinados da API
PublicApiError para respostas de erro estáveis

O schema é seguro para validação de cliente e testes internos de integração. O beta do TypeScript SDK permanece limitado por este schema.

Governança dos Exemplos

Exemplos de curl, JavaScript e Python nestes docs usam os mesmos nomes de campos públicos que o schema:

Authorization: Bearer rvya_sk_...
Idempotency-Key
model
prompt
message
session_id
params
client_request_id

Exemplos de Chat também usam:

chat:create
chat:read
file_id

Exemplos de webhook também usam:

Rivya-Webhook-Signature
Rivya-Webhook-Timestamp
webhooks:manage

Quando um parâmetro de modelo mudar, atualize primeiro o catálogo de modelos e o public serializer. Os docs e o debugger devem consumir essa mesma camada pública em vez de copiar uma tabela separada.

Contrato de OpenAPI e Schema