檢視 Rivya API v1 schema 來源、相容性規則、公開欄位，以及唯讀 OpenAPI JSON 合約。

Rivya API v1 在以下位置公開唯讀 schema 合約：

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

這個 route 是公開合約輸出。它不會讀取使用者 session data，不會提交模型 job，也不會暴露私人帳號資料。

合約來源

合約衍生自：

public API request schemas
public error codes
public API model reference layer
/api/v1/models 使用的同一份模型目錄

模型清單是動態的。不要建立依賴手動撰寫模型數量的整合。

版本政策

目前 API 版本是 v1。

向後相容變更可能包括：

將模型加入 /api/v1/models
新增選用 response 欄位
為模型新增選用 request parameter
新增公開 error code

破壞性變更需要新版本，或已記錄的遷移路徑。

公開欄位邊界

公開 schema 欄位使用公開名稱：

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

不要依賴內部任務儲存欄位。它們不是公開合約的一部分。

Request Schema

POST /api/v1/generations 接受：

model：必填的公開模型 ID
prompt：選用字串，許多模型都會要求
params：包含模型專屬參數的選用物件
client_request_id：你的 trace ID，可選用

請使用模型 API 參考查看模型專屬 params。

由 /api/v1/files 回傳的參考媒體應放在 params.referenceMediaItems 內。schema 會記錄 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 與已簽名影片 metadata。Rivya 不接受頂層 files 欄位放在 POST /api/v1/generations 中。

POST /api/v1/files 接受 multipart form data，包含 file、kind、選用 model 和選用 client_request_id。回應是 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 帳號擁有的檔案回傳公開 metadata；未持久化的已簽名 metadata token 可能會是 null，此時必須重新上傳。

video_metadata_token 會綁定 API 帳號、目標模型、URL、MIME 類型、尺寸、影格率、位元率與上傳位元組大小。它不能取代 duration_token；同時使用這兩種合約的 Video8 與 Wan 3.0 參考影片必須提供兩個 token。Wan 3.0 的音訊播放時間 token 也會綁定 MIME 類型與上傳檔案位元組大小。

對於 wan-3-0-video，params 只接受 seedance_scene、variant、resolution、aspect_ratio、duration、audio、seed 和 referenceMediaItems。文字、影格與參考場景互斥。智慧播放時間為 -1，會預留 30 秒，且不能與參考影片一起使用；任意欄位、未簽名媒體、檔案轉影片與連結轉影片捷徑都會依失敗即封閉原則拒絕。

POST /api/v1/chat/completions 接受 model、message、選用 session_id、選用控制項、選用 Files API file_id 附件，以及選用 client_request_id。它會回傳一則完整的非串流 assistant 訊息。

POST /api/v1/chat/completions/stream 接受相同 request schema，並回傳 text/event-stream，其中包含 session.created、message.delta、message.completed、usage.completed、heartbeat、error 和 done events。Chat API v1 不接受原始 messages array。

Response Schemas

OpenAPI 輸出會記錄這些公開 response shapes：

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 stream event schemas，用於 Chat API
CreditBalance，用於 GET /api/v1/credits
WebhookEndpoint、WebhookEvent、WebhookDelivery 和 WebhookTestResult，用於已簽名 API webhooks
PublicApiError，用於穩定錯誤回應

這份 schema 可以安全用於 client validation 和內部整合測試。TypeScript SDK beta 會持續受這份 schema 約束。

範例治理

這些文件中的 curl、JavaScript 和 Python 範例使用與 schema 相同的公開欄位名稱：

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。文件和 debugger 應該使用同一個公開層，而不是複製另一份表格。

OpenAPI 與 Schema 合約