Rivya API v1 のスキーマソース、互換性ルール、公開フィールド、読み取り専用 OpenAPI JSON 契約を確認します。

Rivya API v1 は、読み取り専用のスキーマ契約を次で公開します。

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

このルートは公開契約出力です。ユーザーセッションデータを読み取らず、モデルジョブを送信せず、非公開のアカウントデータを公開しません。

契約ソース

契約は次から派生します。

公開 API リクエストスキーマ
公開エラーコード
公開 API モデルリファレンスレイヤー
/api/v1/models が使うものと同じモデルカタログ

モデル一覧は動的です。手書きのモデル数に依存する統合を作らないでください。

バージョンポリシー

現在の API バージョンは v1 です。

後方互換の変更には、次が含まれる場合があります。

/api/v1/models にモデルを追加する
任意の応答フィールドを追加する
モデルに任意のリクエストパラメータを追加する
新しい公開エラーコードを追加する

破壊的変更には、新しいバージョンまたは文書化された移行パスが必要です。

公開フィールド境界

公開スキーマフィールドは公開名を使います。

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

内部タスクストレージフィールドに依存しないでください。それらは公開契約の一部ではありません。

リクエストスキーマ

POST /api/v1/generations は次を受け付けます。

model: 必須の公開モデル ID
prompt: 任意の文字列。多くのモデルで必須です
params: モデル固有のパラメータを含む任意のオブジェクト
client_request_id: あなた側のトレース ID 用の任意の文字列

モデル固有の params にはモデル API リファレンスを使ってください。

/api/v1/files が返す参照メディアは params.referenceMediaItems の中に入ります。スキーマは url、kind、任意の name、任意の mimeType、任意の durationSeconds / durationToken、任意の width / height / sizeBytes / imageDimensionsToken、任意の framesPerSecond / videoBitrateMbps / videoMetadataToken を文書化します。Image5、Grok Imagine Image 2.0、Wan 3.0 の参照画像はすべて、元のモデル紐付きアップロード応答の署名済み画像 token と、それに紐付くバイトサイズを必要とします。Layer Decomposition では、文書化された幾何制限も適用されます。Video8 と Wan 3.0 の参照動画はすべて、元のモデル紐付きアップロード応答に含まれる署名済みの長さ token と署名済み動画メタデータを必要とします。Rivya はトップレベルの files フィールドを含む POST /api/v1/generations リクエストを受け付けません。

POST /api/v1/files は、file、kind、任意の model、任意の client_request_id を含む multipart form data を受け付けます。応答は PublicApiFile で、size_bytes、null になり得る画像寸法、image_dimensions_token、null になり得る video_width、video_height、frames_per_second、video_bitrate_mbps、video_file_size_bytes、video_metadata_token を含みます。GET /api/v1/files/{fileId} は、API アカウントが所有するファイルの公開メタデータを返しますが、永続化されなかった署名済みメタデータ token は null の場合があります。その場合は再アップロードして新しい token を取得してください。

video_metadata_token は、API アカウント、対象モデル、URL、MIME type、寸法、フレームレート、ビットレート、アップロードのバイトサイズに紐付きます。これは duration_token の代わりにはなりません。両方の契約を使う Video8 と Wan 3.0 の参照動画では、両方の token を指定する必要があります。Wan 3.0 の音声 duration token は、MIME type とアップロードのバイトサイズにも紐付きます。

wan-3-0-video の params は、seedance_scene、variant、resolution、aspect_ratio、duration、audio、seed、referenceMediaItems だけを受け付けます。テキスト、フレーム、参照の各シーンは相互排他的です。インテリジェント長さは -1 で、30 秒分を予約し、参照動画とは併用できません。任意の追加キー、未署名メディア、ファイルから動画、リンクから動画へのショートカットは fail closed で拒否されます。

POST /api/v1/chat/completions は、model、message、任意の session_id、任意の制御項目、任意の Files API file_id 添付、任意の client_request_id を受け付けます。これは完全な非ストリーミング assistant メッセージを 1 件返します。

POST /api/v1/chat/completions/stream は同じリクエストスキーマを受け付け、text/event-stream として session.created、message.delta、message.completed、usage.completed、heartbeat、error、done イベントを返します。Chat API v1 は生の messages 配列を受け付けません。

応答スキーマ

OpenAPI 出力は、次の公開応答形式を文書化します。

ModelList: GET /api/v1/models 用
PublicApiModel と ModelParam: モデル選択とパラメータフォーム用
PublicApiFile: POST /api/v1/files と GET /api/v1/files/{fileId} 用
ReferenceMediaItem: ファイルに裏付けられた生成パラメータ用
PublicGeneration: 作成応答とステータス応答用
GenerationResult と GenerationError: 完了済みタスク用
ChatCompletionRequest、ChatCompletion、ChatSession、ChatMessage、ChatUsage、ChatCredits、Chat API 用の Chat stream event schemas
CreditBalance: GET /api/v1/credits 用
WebhookEndpoint、WebhookEvent、WebhookDelivery、WebhookTestResult: 署名付き API webhooks 用
PublicApiError: 安定したエラー応答用

このスキーマは、クライアント検証と内部統合テストに安全に使えます。TypeScript SDK beta はこのスキーマに制約され続けます。

例のガバナンス

これらのドキュメント内の curl、JavaScript、Python 例は、スキーマと同じ公開フィールド名を使います。

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

Chat の例では、さらに次を使います。

chat:create
chat:read
file_id

Webhook の例では、さらに次を使います。

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

モデルパラメータが変わる場合は、最初にモデルカタログと public serializer を更新してください。ドキュメントとデバッガーは、別の表をコピーするのではなく、同じ公開レイヤーを消費するべきです。

OpenAPI とスキーマ契約