Prüfe Rivya API v1-Schemaquellen, Kompatibilitätsregeln, öffentliche Felder und den read-only OpenAPI-JSON-Vertrag.

Rivya API v1 stellt einen read-only Schema-Vertrag bereit unter:

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

Diese Route ist ein öffentlicher Vertragsoutput. Sie liest keine Nutzer-Sessiondaten, reicht keine Modelljobs ein und legt keine privaten Kontodaten offen.

Vertragsquellen

Der Vertrag wird abgeleitet aus:

öffentlichen API-Request-Schemas
öffentlichen Fehlercodes
der öffentlichen API-Modellreferenzschicht
demselben Modellkatalog, den /api/v1/models verwendet

Die Modellliste ist dynamisch. Baue keine Integrationen, die von einer manuell geschriebenen Modellanzahl abhängen.

Versionspolicy

Die aktuelle API-Version ist v1.

Rückwärtskompatible Änderungen können umfassen:

ein Modell zu /api/v1/models hinzufügen
ein optionales Response-Feld hinzufügen
einen optionalen Request-Parameter für ein Modell hinzufügen
einen neuen öffentlichen Fehlercode hinzufügen

Breaking Changes erfordern eine neue Version oder einen dokumentierten Migrationspfad.

Grenze öffentlicher Felder

Öffentliche Schemafelder verwenden öffentliche Namen:

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

Verlasse dich nicht auf interne Task-Storage-Felder. Sie sind kein Teil des öffentlichen Vertrags.

Request-Schema

POST /api/v1/generations akzeptiert:

model: erforderliche öffentliche Modell-ID
prompt: optionaler String, von vielen Modellen verlangt
params: optionales Objekt mit modellspezifischen Parametern
client_request_id: optionaler String für deine eigene Trace-ID

Nutze die Modell-API-Referenz für modellspezifische params.

Referenzmedien, die von /api/v1/files zurückgegeben werden, gehören in params.referenceMediaItems. Das Schema dokumentiert url, kind, optionale name und mimeType, optionale durationSeconds / durationToken, optionale width / height / sizeBytes / imageDimensionsToken sowie optionale framesPerSecond / videoBitrateMbps / videoMetadataToken. Jedes Referenzbild für Image5, Grok Imagine Image 2.0 oder Wan 3.0 benötigt den signierten Bild-Token und die gebundene Dateigröße aus der ursprünglichen modellgebundenen Upload-Antwort; Layer Decomposition wendet zusätzlich seine dokumentierten Geometriegrenzen an. Jedes Video8- oder Wan-3.0-Referenzvideo benötigt den signierten Dauer-Token und die signierten Videometadaten aus der ursprünglichen modellgebundenen Upload-Antwort. Rivya akzeptiert kein top-level Feld files in POST /api/v1/generations.

POST /api/v1/files akzeptiert Multipart-Formdaten mit file, kind, optional model und optional client_request_id. Die Antwort ist PublicApiFile und enthält size_bytes, gegebenenfalls Bildabmessungen, image_dimensions_token sowie gegebenenfalls video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes und video_metadata_token. GET /api/v1/files/{fileId} gibt öffentliche Metadaten für Dateien zurück, die dem API-Konto gehören. Ein signierter Metadaten-Token, der nicht persistiert wurde, kann dabei null sein und muss durch erneutes Hochladen ersetzt werden.

video_metadata_token ist an API-Konto, Zielmodell, URL, MIME-Typ, Abmessungen, Bildrate, Bitrate und Byte-Größe des Uploads gebunden. Er ersetzt duration_token nicht; Video8- und Wan-3.0-Referenzvideos, die beide Verträge verwenden, müssen beide Token bereitstellen. Wan-3.0-Audio-Dauer-Token binden außerdem MIME-Typ und Upload-Größe in Byte.

Für wan-3-0-video akzeptiert params nur seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed und referenceMediaItems. Text-, Frame- und Referenzszenen schließen sich gegenseitig aus. Intelligente Dauer ist -1, reserviert 30 Sekunden und ist mit Referenzvideo ungültig; beliebige Schlüssel, unsignierte Medien sowie Datei-zu-Video- und Link-zu-Video-Kurzpfade werden nach dem Fail-Closed-Prinzip abgelehnt.

POST /api/v1/chat/completions akzeptiert model, message, optional session_id, optionale Controls, optionale Files API-file_id-Anhänge und optional client_request_id. Es gibt eine vollständige nicht streamende Assistant-Nachricht zurück.

POST /api/v1/chat/completions/stream akzeptiert dasselbe Request-Schema und gibt text/event-stream mit session.created, message.delta, message.completed, usage.completed, heartbeat, error und done Events zurück. Chat API v1 akzeptiert kein rohes messages-Array.

Response-Schemas

Der OpenAPI-Output dokumentiert diese öffentlichen Response-Formen:

ModelList für GET /api/v1/models
PublicApiModel und ModelParam für Modellauswahl und Parameterformulare
PublicApiFile für POST /api/v1/files und GET /api/v1/files/{fileId}
ReferenceMediaItem für dateibasierte Generation-Parameter
PublicGeneration für Create- und Status-Antworten
GenerationResult und GenerationError für abgeschlossene Tasks
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits und Chat-Stream-Event-Schemas für Chat API
CreditBalance für GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery und WebhookTestResult für signierte API-Webhooks
PublicApiError für stabile Fehlerantworten

Das Schema kann sicher für Client-Validierung und interne Integrationstests verwendet werden. Die TypeScript-SDK-Beta bleibt durch dieses Schema begrenzt.

Beispiel-Governance

curl-, JavaScript- und Python-Beispiele in diesen Docs verwenden dieselben öffentlichen Feldnamen wie das Schema:

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

Chat-Beispiele verwenden zusätzlich:

chat:create
chat:read
file_id

Webhook-Beispiele verwenden zusätzlich:

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

Wenn sich ein Modellparameter ändert, aktualisiere zuerst Modellkatalog und Public Serializer. Docs und Debugger sollten dieselbe öffentliche Schicht verwenden, statt eine getrennte Tabelle zu kopieren.

OpenAPI- und Schema-Vertrag