Rivya API 總覽

當目前部署已啟用公開 API，且你的帳號具備存取權限時，Rivya API v1 就是讓自有產品呼叫 Rivya 已支援模型能力的開發者規格。

目前已實作的規格涵蓋非同步圖片、影片與音訊生成，以及支援非串流或 SSE 串流回應的 Chat API 對話。它使用 Rivya 模型 ID 與帳號點數；生成任務使用公開任務 ID，Chat API 則使用伺服器端聊天工作階段。文件列出某條路由，不代表每個環境、帳號或目錄模型都能呼叫；整合前請確認即時存取權限與模型就緒狀態。

API 適合做什麼

當你想要以下能力時，請使用 API：

• 從自己的應用程式提交圖片、影片或音訊生成任務

• 送出非串流或串流聊天回合，並繼續 API 建立的聊天工作階段

• 將帳單保留在同一個 Rivya 帳號點數錢包中

• 依公開任務 ID 輪詢任務狀態

• 對正式環境請求使用冪等重試，提高安全性

• 讓 Studio 與 API 的用量維持在同一個帳號範圍內

API 是 Rivya 的產品層。公開回應只使用 Rivya 名稱和公開欄位。

目前版本範圍

已實作的 v1 端點包括：

• GET /api/v1/models

• POST /api/v1/generations

• POST /api/v1/files

• GET /api/v1/files/{fileId}

• POST /api/v1/chat/completions

• GET /api/v1/chat/sessions

• GET /api/v1/chat/sessions/{sessionId}

• GET /api/v1/generations/{taskId}

• GET /api/v1/credits

• GET /api/v1/webhooks

• POST /api/v1/webhooks

• GET /api/v1/webhook-events

• GET /api/v1/openapi.json

目前規格包含用於非同步生成結果的簽名 Webhook、Chat API，以及支援伺服器端串流的 TypeScript SDK 測試版。呼叫 Webhook 相關端點前，目前部署必須已啟用 Webhook 功能與公開 API 存取權限。

驗證

生成、狀態與點數端點需要：

Authorization: Bearer rvya_sk_...

請前往 API 金鑰設定建立和輪替金鑰。在正式環境使用金鑰前，請閱讀 API 驗證。

計費模型

API 呼叫使用與 Studio 相同的 Rivya 帳號點數。

生成任務會在開始時預留或消耗點數。Chat 回合會在模型呼叫前預留點數，並在助理訊息儲存時依權杖用量結算最終點數。如果生成或聊天回合依照既有 Rivya 失敗規則失敗，會套用相同的退款處理。

請閱讀 API 點數 和 Rivya 點數與帳單，了解使用者可見的錢包模型。

首次整合路徑

1. 在設定中建立 API 金鑰。

2. 呼叫 列出 API 模型 選擇公開模型 ID。

3. 閱讀 模型 API 參考 查看該模型的參數。

4. 如果模型需要參考媒體，請使用 Files API 上傳。

5. 使用 建立生成任務 提交任務。

6. 輪詢生成狀態，直到任務成功或失敗。如果目前部署與帳號已啟用 Webhook，也可以改為訂閱 API Webhooks，接收已簽名的完成事件。

7. 對於聊天模型，請使用 Chat API，而不是生成端點。Chat 圖片附件必須引用 Files API 的 file_id 值。

相關頁面

• API 快速開始

• API 驗證

• Rivya TypeScript SDK

• 模型 API 參考

• Chat API

• API Webhooks

• API 錯誤與限制