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 を文書化します。Rivya は POST /api/v1/generations でトップレベルの files フィールドを受け付けません。

POST /api/v1/files は、file、kind、任意の model、任意の client_request_id を含む multipart form data を受け付けます。応答は PublicApiFile です。GET /api/v1/files/{fileId} は、API アカウントが所有するファイルについて同じ公開ファイルメタデータを返します。

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

POST /api/v1/chat/completions/stream は同じリクエストスキーマを受け付け、session.created、message.delta、message.completed、usage.completed、heartbeat、error、done イベントを含む text/event-stream を返します。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 とスキーマ契約