Examinez les sources de schéma Rivya API v1, les règles de compatibilité, les champs publics et le contrat OpenAPI JSON en lecture seule.

Rivya API v1 expose un contrat de schéma en lecture seule à cette adresse :

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

Cette route est une sortie de contrat publique. Elle ne lit pas les données de session utilisateur, ne soumet pas de jobs modèle et n'expose pas de données privées de compte.

Sources du contrat

Le contrat est dérivé de :

schémas de requêtes de l'API publique
codes d'erreur publics
couche publique de référence des modèles API
même catalogue de modèles que celui utilisé par /api/v1/models

La liste des modèles est dynamique. Ne construisez pas d'intégrations qui dépendent d'un nombre de modèles écrit manuellement.

Politique de version

La version actuelle de l'API est v1.

Les changements rétrocompatibles peuvent inclure :

l'ajout d'un modèle à /api/v1/models
l'ajout d'un champ de réponse optionnel
l'ajout d'un paramètre de requête optionnel pour un modèle
l'ajout d'un nouveau code d'erreur public

Les changements cassants exigent une nouvelle version ou un chemin de migration documenté.

Limite des champs publics

Les champs du schéma public utilisent des noms publics :

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

Ne dépendez pas des champs internes de stockage des tâches. Ils ne font pas partie du contrat public.

Schéma de requête

POST /api/v1/generations accepte :

model : ID public du modèle requis
prompt : chaîne optionnelle, requise par de nombreux modèles
params : objet optionnel avec paramètres propres au modèle
client_request_id : chaîne optionnelle pour votre propre ID de trace

Utilisez la référence API des modèles pour les params propres à chaque modèle.

Les médias de référence renvoyés par /api/v1/files doivent être placés dans params.referenceMediaItems. Le schéma documente url, kind, name optionnel, mimeType optionnel, durationSeconds / durationToken optionnels, width / height / sizeBytes / imageDimensionsToken optionnels ainsi que framesPerSecond / videoBitrateMbps / videoMetadataToken optionnels. Chaque image de référence Image5, Grok Imagine Image 2.0 ou Wan 3.0 exige le token d'image signé et la taille en octets liés à la réponse d'import d'origine associée au modèle ; Layer Decomposition applique aussi les limites géométriques documentées. Chaque vidéo de référence Video8 ou Wan 3.0 exige le token de durée signé et les métadonnées vidéo signées de la réponse d'import d'origine liée au modèle. Rivya n'accepte pas de champ files au niveau racine dans POST /api/v1/generations.

POST /api/v1/files accepte des données de formulaire multipart avec file, kind, model optionnel et client_request_id optionnel. La réponse est PublicApiFile et inclut size_bytes, les dimensions d'image éventuellement nulles, image_dimensions_token, ainsi que video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes et video_metadata_token, qui peuvent être nuls. GET /api/v1/files/{fileId} renvoie les métadonnées publiques des fichiers appartenant au compte API, mais un token de métadonnées signé qui n'a pas été persisté peut être null et doit être remplacé en réimportant le fichier.

video_metadata_token est lié au compte API, au modèle cible, à l'URL, au type MIME, aux dimensions, à la fréquence d'images, au débit et à la taille importée en octets. Il ne remplace pas duration_token ; les vidéos de référence Video8 et Wan 3.0 qui utilisent les deux contrats doivent fournir les deux tokens. Les tokens de durée audio Wan 3.0 lient aussi le type MIME et la taille importée en octets.

Pour wan-3-0-video, params accepte uniquement seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed et referenceMediaItems. Les scènes texte, images clés et référence sont mutuellement exclusives. La durée intelligente vaut -1, réserve 30 secondes et n'est pas valide avec une vidéo de référence ; les clés arbitraires, les médias non signés et les raccourcis fichier-vers-vidéo ou lien-vers-vidéo sont rejetés selon le principe fail closed.

POST /api/v1/chat/completions accepte model, message, session_id optionnel, les contrôles optionnels, les pièces jointes Files API file_id optionnelles et client_request_id optionnel. Il renvoie un message assistant complet sans streaming.

POST /api/v1/chat/completions/stream accepte le même schéma de requête et renvoie text/event-stream avec les événements session.created, message.delta, message.completed, usage.completed, heartbeat, error et done. Chat API v1 n'accepte pas de tableau brut messages.

Schémas de réponse

La sortie OpenAPI documente ces formes de réponse publiques :

ModelList pour GET /api/v1/models
PublicApiModel et ModelParam pour la sélection de modèle et les formulaires de paramètres
PublicApiFile pour POST /api/v1/files et GET /api/v1/files/{fileId}
ReferenceMediaItem pour les paramètres de génération adossés à des fichiers
PublicGeneration pour les réponses de création et de statut
GenerationResult et GenerationError pour les tâches terminées
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits et les schémas d'événements de stream Chat pour l'API Chat
CreditBalance pour GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery et WebhookTestResult pour les webhooks API signés
PublicApiError pour les réponses d'erreur stables

Le schéma peut être utilisé en sécurité pour la validation client et les tests d'intégration internes. La bêta du SDK TypeScript reste contrainte par ce schéma.

Gouvernance des exemples

Les exemples curl, JavaScript et Python de cette documentation utilisent les mêmes noms de champs publics que le schéma :

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

Les exemples Chat utilisent aussi :

chat:create
chat:read
file_id

Les exemples webhook utilisent aussi :

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

Quand un paramètre de modèle change, mettez d'abord à jour le catalogue de modèles et le sérialiseur public. La documentation et le débogueur doivent consommer cette même couche publique au lieu de copier un tableau séparé.

Contrat OpenAPI et schéma