Rivya Journal
作者
分類
繼續探索
繼續閱讀 Rivya 團隊整理的相關指南、產品筆記和工作流拆解。
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 設定連結，以及安全的除錯流程，從這裡進入最合適。
當人還在選模型、調整提示詞、檢視輸出並決定下一步時，Studio 很有用。
當這個決策已經變成可重複的產品或營運工作流時，API 很有用。
常見例子包括：
產品在使用者提交創作簡報後生成圖片變體
行銷工作流需要根據結構化 campaign 輸入建立視覺草稿
內部工具需要提交影片或音訊任務，而不必要求某個人打開瀏覽器
支援或內容系統想把一次 Chat 模型回合放進自己的介面
後端服務希望在生成任務完成時收到簽名 callback
在這些情況下，Rivya API 讓工作維持連接到同一個 Rivya 帳戶，而不是為計費、模型選擇和任務狀態另建一套分離堆疊。
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 有自己的公開檔案邊界是有原因的。
輪詢是最容易開始的整合路徑。提交生成任務，儲存公開 task ID，然後輪詢直到成功或失敗。
當整合更接近正式產品流程時，Webhooks 會變得有用：
你不想讓 worker 輪詢每一個任務
你的應用程式需要在生成完成時更新一筆記錄
你想要一個已簽名、可以安全重試的事件
失敗任務需要進入清楚的恢復路徑
簽名事件合約請使用 API Webhooks。Webhook receiver 要保持範圍克制：驗證簽名、處理重複事件，並避免把 secret 值寫進 logs。
最好的第一個 API 專案通常很小，而且很具體。
例如：
在 settings 建立 API key
呼叫模型清單
選擇一個可用模型
使用 idempotency key 提交一個生成任務
輪詢 status endpoint
檢查前後積分
之後再加入 Files API、Chat API 或 Webhooks
這條路徑能讓你先取得一個可運作的整合，而不是在第一次測試裡混入所有 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 工作流。
