Revizuieste sursele de schema Rivya API v1, regulile de compatibilitate, campurile publice si contractul JSON OpenAPI read-only.

Rivya API v1 expune un contract de schema read-only la:

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

Aceasta ruta este un output public de contract. Nu citeste date de sesiune ale utilizatorului, nu trimite joburi de model si nu expune date private ale contului.

Sursele contractului

Contractul este derivat din:

schemele cererilor Public API
codurile publice de eroare
stratul public de referinta pentru modelele API
acelasi catalog de modele folosit de /api/v1/models

Lista de modele este dinamica. Nu construi integrari care depind de un numar de modele scris manual.

Politica de versiuni

Versiunea curenta a API-ului este v1.

Schimbarile compatibile inapoi pot include:

adaugarea unui model in /api/v1/models
adaugarea unui camp optional in raspuns
adaugarea unui parametru optional de cerere pentru un model
adaugarea unui nou cod public de eroare

Schimbarile incompatibile necesita o versiune noua sau o cale de migrare documentata.

Limita campurilor publice

Campurile de schema publica folosesc nume publice:

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

Nu depinde de campuri interne de stocare a sarcinilor. Ele nu fac parte din contractul public.

Schema cererii

POST /api/v1/generations accepta:

model: ID public de model, obligatoriu
prompt: string optional, necesar pentru multe modele
params: obiect optional cu parametri specifici modelului
client_request_id: string optional pentru propriul tau ID de trasabilitate

Foloseste Referinta API pentru modele pentru params specifice modelului.

Media de referinta returnata de /api/v1/files apartine in params.referenceMediaItems. Schema documenteaza url, kind, name optional, mimeType optional, durationSeconds optional si durationToken optional. Rivya nu accepta un camp top-level files in POST /api/v1/generations.

POST /api/v1/files accepta date formular multipart cu file, kind, model optional si client_request_id optional. Raspunsul este PublicApiFile. GET /api/v1/files/{fileId} returneaza aceleasi metadate publice de fisier pentru fisiere detinute de contul API.

POST /api/v1/chat/completions accepta model, message, session_id optional, controale optionale, atasamente Files API file_id optionale si client_request_id optional. Returneaza un mesaj complet de asistent non-streaming.

POST /api/v1/chat/completions/stream accepta aceeasi schema de cerere si returneaza text/event-stream cu evenimente session.created, message.delta, message.completed, usage.completed, heartbeat, error si done. Chat API v1 nu accepta un array brut messages.

Scheme de raspuns

Outputul OpenAPI documenteaza aceste forme publice de raspuns:

ModelList pentru GET /api/v1/models
PublicApiModel si ModelParam pentru selectia modelelor si formularele de parametri
PublicApiFile pentru POST /api/v1/files si GET /api/v1/files/{fileId}
ReferenceMediaItem pentru parametri de generare sustinuti de fisiere
PublicGeneration pentru raspunsuri de creare si status
GenerationResult si GenerationError pentru sarcini finalizate
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits si schemele de evenimente stream Chat pentru Chat API
CreditBalance pentru GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery si WebhookTestResult pentru webhookuri API semnate
PublicApiError pentru raspunsuri stabile de eroare

Schema este sigura pentru validare de client si teste interne de integrare. Beta-ul TypeScript SDK ramane constrans de aceasta schema.

Guvernanta exemplelor

Exemplele curl, JavaScript si Python din aceste documente folosesc aceleasi nume de campuri publice ca schema:

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

Exemplele Chat folosesc suplimentar:

chat:create
chat:read
file_id

Exemplele Webhook folosesc suplimentar:

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

Cand un parametru de model se schimba, actualizeaza mai intai catalogul de modele si serializerul public. Documentatia si debuggerul ar trebui sa consume acelasi strat public in loc sa copieze un tabel separat.

Contract OpenAPI si schema