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 / durationToken opzionali, width / height / sizeBytes / imageDimensionsToken opzionali e framesPerSecond / videoBitrateMbps / videoMetadataToken opzionali. Ogni immagine di riferimento Image5, Grok Imagine Image 2.0 o Wan 3.0 richiede il token immagine firmato e la dimensione in byte associata della risposta originale all'upload legato al modello; Layer Decomposition applica anche i limiti geometrici documentati. Ogni video di riferimento Video8 o Wan 3.0 richiede il token di durata firmato e i metadati video firmati della risposta originale all'upload associato al modello. 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 e include size_bytes, le dimensioni dell'immagine facoltative, image_dimensions_token e i campi video facoltativi video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes e video_metadata_token. GET /api/v1/files/{fileId} restituisce i metadati pubblici dei file appartenenti all'account API, ma un token di metadati firmato che non è stato persistito può risultare null e deve essere sostituito caricando nuovamente il file.

video_metadata_token è associato all'account API, al modello di destinazione, all'URL, al tipo MIME, alle dimensioni, alla frequenza dei fotogrammi, al bitrate e alla dimensione dell'upload in byte. Non sostituisce duration_token: i video di riferimento Video8 e Wan 3.0 che usano entrambi i contratti devono fornire entrambi i token. I token di durata audio di Wan 3.0 vincolano anche il tipo MIME e la dimensione dell'upload in byte.

Per wan-3-0-video, params accetta solo seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed e referenceMediaItems. Le scene di testo, fotogrammi e riferimento sono mutuamente esclusive. La durata intelligente è -1, prenota 30 secondi e non è valida con un video di riferimento; chiavi arbitrarie, media non firmati e scorciatoie da file a video o da link a video vengono rifiutati secondo il principio di chiusura in caso di errore.

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