Rivya API 是讓開發者從自己的產品、腳本或工作流使用 Rivya 模型能力的接入路徑。
它不是 Rivya Studio 之外的另一套產品。它使用同一個帳戶邊界、同一個積分錢包，以及使用者在 Rivya 各處看到的同一個公開模型層。差別在於工作如何開始：你的應用程式不透過 Studio 點選操作，而是用 API key 發送請求。
如果你需要 endpoint 細節，請先讀 Rivya API Overview 和 Rivya API Quickstart。這篇文章是產品層級的說明：API 用來做什麼、適合放在哪裡，以及什麼時候不該把它當成第一條路徑。
簡短版本
Rivya API v1 讓已登入帳戶建立 API key，並從網頁介面之外呼叫 Rivya 模型能力。
目前的 API 範圍包括：
- 透過 API 模型清單探索模型
- 非同步圖片、影片和音訊生成任務
- 需要參考媒體的模型可使用 Files API 上傳
- 使用公開 task ID 輪詢生成狀態
- 檢查帳戶積分
- Chat API 回合，包括可選的 SSE streaming
- 生成完成時的簽名 webhook
- 給需要客戶端封裝的團隊使用的 TypeScript SDK beta
公開開發者入口是 Developers。如果你想要導覽式總覽、API key 設定連結，以及安全的除錯流程，從這裡進入最合適。
Rivya 為什麼需要 API
當人還在選模型、調整提示詞、檢視輸出並決定下一步時，Studio 很有用。
當這個決策已經變成可重複的產品或營運工作流時，API 很有用。
常見例子包括：
- 產品在使用者提交創作簡報後生成圖片變體
- 行銷工作流需要根據結構化 campaign 輸入建立視覺草稿
- 內部工具需要提交影片或音訊任務，而不必要求某個人打開瀏覽器
- 支援或內容系統想把一次 Chat 模型回合放進自己的介面
- 後端服務希望在生成任務完成時收到簽名 callback
在這些情況下，Rivya API 讓工作維持連接到同一個 Rivya 帳戶，而不是為計費、模型選擇和任務狀態另建一套分離堆疊。
API 不取代什麼
API 不會取代所有直接使用 Rivya 的理由。
遇到以下情況時，請使用 Studio 或公開工作介面：
- 提示詞仍然需要人工探索
- 模型選擇尚未穩定
- 創作者需要以視覺方式比較輸出
- 專案依賴已儲存歷史和人工複核
- 團隊尚未決定哪種輸入與輸出格式應該變成可重複流程
當工作流清楚到足以自動化時，再使用 API。
這個邊界很重要。模糊的創意問題通常應先放在 Studio。具備可預期輸入的已知產品流程，才適合移到 API。
主要組成
可以把 API 想成六個互相連接的部分。
| 組成 | 負責內容 | 下一步閱讀 |
|---|---|---|
| API keys | 從你的帳戶進行伺服器對伺服器存取 | API Authentication |
| Models | 公開模型 ID 和可用狀態資訊 | API Models |
| Generations | 非同步圖片、影片和音訊任務 | Create Generation |
| Files | 參考圖片、影片或音訊上傳 | Files API |
| Chat | 非串流或串流 Chat 回合 | Chat API |
| Webhooks | 生成任務的簽名完成事件 | API Webhooks |
API 文件才是請求和回應形狀的來源。這篇文章只協助你判斷第一個需要的是哪一部分。
積分如何運作
API 使用量會消耗與 Studio 相同的 Rivya 帳戶積分錢包。
也就是說，API 不是匿名模型代理。每個請求都屬於一個 Rivya 帳戶，使用該帳戶建立的 API key，並遵循 API Credits 中描述的同一個產品層級積分邊界。
這對團隊很有用，因為 Studio 實驗和 API 使用會留在同一個營運模型中。你可以先手動測試模型，再把可重複的部分移進整合流程，而不必建立第二層計費系統。
檔案如何接入
有些模型只靠文字就能執行。其他模型需要參考圖片、影片或音訊檔案。
對 API 整合來說，這些參考素材應該透過 Files API。上傳會建立受管理的檔案記錄，之後可以傳入支援的模型參數。
實務規則很簡單：
- 如果模型接受純文字輸入，先從 generation endpoint 開始
- 如果模型需要參考媒體，先上傳檔案
- 如果模型是支援圖片附件的 chat model，使用 Chat API 和 file ID
不要把整合設計成依賴只能在瀏覽器中使用的上傳流程，或依賴已儲存的 Studio session。API 有自己的公開檔案邊界是有原因的。
Webhooks 在哪裡有用
輪詢是最容易開始的整合路徑。提交生成任務，儲存公開 task ID，然後輪詢直到成功或失敗。
當整合更接近正式產品流程時，Webhooks 會變得有用：
- 你不想讓 worker 輪詢每一個任務
- 你的應用程式需要在生成完成時更新一筆記錄
- 你想要一個已簽名、可以安全重試的事件
- 失敗任務需要進入清楚的恢復路徑
簽名事件合約請使用 API Webhooks。Webhook receiver 要保持範圍克制：驗證簽名、處理重複事件，並避免把 secret 值寫進 logs。
好的第一個 API 專案
最好的第一個 API 專案通常很小，而且很具體。
例如：
- 在 settings 建立 API key
- 呼叫模型清單
- 選擇一個可用模型
- 使用 idempotency key 提交一個生成任務
- 輪詢 status endpoint
- 檢查前後積分
- 之後再加入 Files API、Chat API 或 Webhooks
這條路徑能讓你先取得一個可運作的整合，而不是在第一次測試裡混入所有 API 功能。
什麼時候 API 是錯的起點
在以下情況下，API 很可能不是正確的第一步：
- 團隊尚未選定模型系列
- 期望輸出每次執行都還在變動
- 提示詞依賴人工品味和複核
- 整合會讓需要理解積分使用情況的人看不見消耗
- 產品在需要自動化之前，還需要一個公開 demo
遇到這些情況，請先從 Image、Video、Audio、Chat 或 AI Models 開始。當路徑可以重複時，再把穩定的部分移到 API。
下一步去哪裡
- 打開 Developers，查看公開 API hub 和 debugger。
- 閱讀 Rivya API Quickstart，發送第一個安全請求。
- 在把 key 放到伺服器之前，先讀 API Authentication。
- 選擇 model ID 之前，先讀 API Models。
- 如果產品邊界仍不清楚，讀 什麼時候該用 Rivya API 而不是 Studio。
- 當你正在規劃完整的圖片、影片、音訊或 chat 整合時，讀 如何用 Rivya API 建置多模態 AI 工作流。
