Rivedi sorgenti schema Rivya API v1, regole di compatibilità, campi pubblici e contratto OpenAPI JSON in sola lettura.

Rivya API v1 espone un contratto schema in sola lettura a:

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

Questa route è un output di contratto pubblico. Non legge dati di sessione utente, non invia job modello e non espone dati privati dell'account.

Sorgenti del contratto

Il contratto deriva da:

schema delle richieste API pubbliche
codici di errore pubblici
livello pubblico del riferimento modelli API
lo stesso catalogo modelli usato da /api/v1/models

L'elenco dei modelli è dinamico. Non costruire integrazioni che dipendono da un conteggio modelli scritto manualmente.

Policy di versione

La versione API attuale è v1.

Le modifiche retrocompatibili possono includere:

aggiunta di un modello a /api/v1/models
aggiunta di un campo di risposta opzionale
aggiunta di un parametro di richiesta opzionale per un modello
aggiunta di un nuovo codice di errore pubblico

Le modifiche breaking richiedono una nuova versione o un percorso di migrazione documentato.

Confine dei campi pubblici

I campi dello schema pubblico usano nomi pubblici:

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

Non dipendere dai campi interni di storage dei task. Non fanno parte del contratto pubblico.

Schema di richiesta

POST /api/v1/generations accetta:

model: ID pubblico del modello, obbligatorio
prompt: stringa opzionale, richiesta da molti modelli
params: oggetto opzionale con parametri specifici del modello
client_request_id: stringa opzionale per il tuo ID di tracciamento

Usa riferimento API dei modelli per i params specifici del modello.

I media di riferimento restituiti da /api/v1/files appartengono a params.referenceMediaItems. Lo schema documenta url, kind, name opzionale, mimeType opzionale, durationSeconds opzionale e durationToken opzionale. Rivya non accetta un campo files al livello principale in POST /api/v1/generations.

POST /api/v1/files accetta multipart form data con file, kind, model opzionale e client_request_id opzionale. La risposta è PublicApiFile. GET /api/v1/files/{fileId} restituisce gli stessi metadati pubblici del file per file posseduti dall'account API.

POST /api/v1/chat/completions accetta model, message, session_id opzionale, controlli opzionali, allegati Files API file_id opzionali e client_request_id opzionale. Restituisce un messaggio assistant completo non streaming.

POST /api/v1/chat/completions/stream accetta lo stesso schema di richiesta e restituisce text/event-stream con eventi session.created, message.delta, message.completed, usage.completed, heartbeat, error e done. Chat API v1 non accetta un array raw messages.

Schemi di risposta

L'output OpenAPI documenta queste forme di risposta pubbliche:

ModelList per GET /api/v1/models
PublicApiModel e ModelParam per selezione modello e form parametri
PublicApiFile per POST /api/v1/files e GET /api/v1/files/{fileId}
ReferenceMediaItem per parametri di generazione basati su file
PublicGeneration per risposte di creazione e stato
GenerationResult e GenerationError per task completati
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits e schemi degli eventi stream Chat per Chat API
CreditBalance per GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery e WebhookTestResult per webhook API firmati
PublicApiError per risposte di errore stabili

Lo schema è sicuro da usare per validazione client e test di integrazione interni. La beta del TypeScript SDK resta vincolata da questo schema.

Governance degli esempi

Gli esempi curl, JavaScript e Python in questi documenti usano gli stessi nomi di campo pubblici dello schema:

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

Gli esempi Chat usano inoltre:

chat:create
chat:read
file_id

Gli esempi webhook usano inoltre:

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

Quando cambia un parametro di modello, aggiorna prima il catalogo modelli e il serializer pubblico. Documenti e debugger dovrebbero consumare lo stesso livello pubblico invece di copiare una tabella separata.

OpenAPI e contratto dello schema