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, optional name, optional mimeType, optional durationSeconds und optional durationToken. 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. GET /api/v1/files/{fileId} gibt dieselben öffentlichen Dateimetadaten für Dateien zurück, die dem API-Konto gehören.

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