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 tarefas 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 / durationToken opcionais, width / height / sizeBytes / imageDimensionsToken opcionais e framesPerSecond / videoBitrateMbps / videoMetadataToken opcionais. Toda imagem de referência do Image5, do Grok Imagine Image 2.0 ou do Wan 3.0 exige o token de imagem assinado e o tamanho em bytes vinculados à resposta original do upload associado ao modelo; o Layer Decomposition também aplica os limites geométricos documentados. Todo vídeo de referência do Video8 ou do Wan 3.0 exige o token de duração assinado e os metadados de vídeo assinados da resposta original do upload vinculado ao modelo. 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, incluindo size_bytes, dimensões de imagem que podem ser nulas, image_dimensions_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes e video_metadata_token, todos estes campos de vídeo podendo ser nulos. GET /api/v1/files/{fileId} retorna metadados públicos de arquivos pertencentes à conta da API, mas um token de metadados assinado que não foi persistido pode ser null e deve ser substituído por meio de um novo upload.

video_metadata_token fica vinculado à conta da API, ao modelo de destino, à URL, ao tipo MIME, às dimensões, à taxa de quadros, à taxa de bits e ao tamanho do upload em bytes. Ele não substitui duration_token; vídeos de referência do Video8 e do Wan 3.0 que usam os dois contratos devem fornecer ambos os tokens. Os tokens de duração de áudio do Wan 3.0 também vinculam o tipo MIME e o tamanho do upload em bytes.

Para wan-3-0-video, params aceita apenas seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed e referenceMediaItems. As cenas de texto, quadros e referência são mutuamente exclusivas. A duração inteligente é -1, reserva 30 segundos e é inválida com vídeo de referência; chaves arbitrárias, mídia não assinada e atalhos de arquivo para vídeo ou de link para vídeo são rejeitados de forma fechada.

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 serializador público. A documentação e o depurador devem consumir essa mesma camada pública em vez de copiar uma tabela separada.

Contrato de OpenAPI e Schema