檢視 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。Rivya 不接受頂層 files 欄位放在 POST /api/v1/generations 中。

POST /api/v1/files 接受 multipart form data，包含 file、kind、選用 model 和選用 client_request_id。回應是 PublicApiFile。GET /api/v1/files/{fileId} 會為 API 帳號擁有的檔案回傳相同公開檔案 metadata。

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 合約