最容易犯的錯，是把 Rivya API 和 Rivya Studio 當成互相競爭的兩條路。
更準確的理解是：它們是同一套產品裡的兩個階段。Studio 適合讓人探索、選擇、複核，並以視覺方式延續工作。API 則適合把已經穩定的工作流接入另一個產品、腳本或後端流程。
如果你還在熟悉 API 表面，先讀 Rivya API 是什麼？。這篇更聚焦：如何判斷某個具體任務應該留在 Studio，還是放進 API。
一張表做判斷
| 問題 | 更適合 Studio 的情況 | 更適合 API 的情況 |
|---|---|---|
| 輸出還在探索嗎？ | 是 | 否，工作流已經可重複 |
| 需要人比較結果嗎？ | 需要 | 只在你的應用收到結果後才需要 |
| 模型選擇穩定嗎？ | 還不穩定 | 已穩定，或可從 API 模型列表選擇 |
| 任務需要參考素材嗎？ | 人還在準備素材 | 你的應用可以透過 Files API 上傳 |
| 結果需要更新另一個系統嗎？ | 暫時不需要 | 需要，透過輪詢或 Webhook |
| 積分使用需要保持可見嗎？ | 需要，尤其在測試時 | 也需要，但透過帳戶層級 API 控制處理 |
這不是在比較哪個入口更進階，而是在判斷任務是否已經準備好被自動化。
工作還在變動時，用 Studio
當人的判斷仍然是主要工作時，Studio 是更合適的位置。
包括：
- 在圖片、影片、音訊或 Chat 模型之間選擇
- 測試某個提示詞方向是否值得保留
- 並排比較視覺結果
- 判斷參考素材到底有幫助還是造成干擾
- 使用已儲存的歷史，從先前結果繼續工作
創意工作尤其如此。如果 brief 還不穩定，自動化請求通常只會讓混亂變快，而不是讓問題變小。
工作流可重複時，用 API
當輸入和下一步已經足夠可預測，API 就會成為更好的路徑。
好的信號包括：
- 你的產品已經知道需要哪個模型或模型類別
- 使用者輸入可以映射成穩定的請求 body
- 後端任務可以輪詢狀態，不需要有人盯著畫面
- Webhook 可以在任務完成時更新正確的記錄
- 應用可以向團隊或帳戶負責人說明積分使用
到了這個階段，每次都使用 Studio 執行，反而可能變成較慢的路徑。API 讓你的產品可以直接啟動任務。
一個實用邊界：發現與接入
用 Studio 做發現。
用 API 做接入。
發現指的是：
- 「我們該用哪個模型？」
- 「什麼提示詞形狀有效？」
- 「參考素材是否改善這個任務？」
- 「輸出品質對這個用途是否夠好？」
接入指的是：
- 「這個使用者動作應該建立一個生成任務。」
- 「這個任務應該以冪等方式重試。」
- 「這個檔案應該上傳並附加到模型請求。」
- 「這個已完成的任務應該更新我們的產品記錄。」
這條邊界可以避免 API 變成藏在後台的實驗入口。
積分應該如何影響決策
Studio 和 API 都會使用同一個 Rivya 帳戶的積分。
這表示積分行為應該成為產品設計的一部分，而不是事後才補上的說明。
當團隊還需要理解成本形狀時，先用 Studio。當任務穩定到產品可以解釋積分何時可能被預留或消耗時，再用 API。
目前公開規則請讀 API Credits。如果某個工作流貴到無法向帳戶負責人說清楚，它就還不適合 API 自動化。
檔案會如何改變選擇
參考素材通常是接入變得更正式的地方。
在 Studio 裡，人可以上傳、檢查、重試，並判斷檔案是否足夠好。在 API 裡，你的產品需要透過 Files API 有意識地處理檔案路徑。
以下情況用 Studio：
- 參考圖片、影片或音訊仍然需要人工清理
- 團隊還不確定哪個參考素材應該引導模型
- 檔案規則還無法向使用者說清楚
以下情況用 API：
- 應用可以安全收集檔案
- 模型的參考要求已經明確
- 檔案可以在生成或 Chat 請求前先上傳
- 錯誤可以在你自己的產品裡清楚呈現，不會隱藏實際發生的事
Files API 是有用的橋梁，但它不會移除你設計檔案體驗的責任。
Chat 會如何改變選擇
Chat 可以屬於兩邊。
當人正在探索、寫作、複核或決策時，直接使用 Rivya Chat。
當 Chat 回合需要存在於你自己的產品或伺服器工作流裡時，使用 Chat API。這可以包含非 streaming 回合、可選的 SSE streaming、由 API 建立的 session，以及受支援的檔案附件。
關鍵問題是：對話應該活在哪裡？如果對話是 Rivya 工作的一部分，就使用 Rivya。如果對話是你產品體驗的一部分，就使用 API。
Webhook 什麼時候是一個信號
如果你的工作流需要 API Webhooks，它很可能已經走過了手動 Studio 階段。
當另一個系統需要回應已完成的生成任務時，Webhook 很有用：
- 標記素材已就緒
- 通知使用者
- 推進複核步驟
- 把失敗任務轉入支援或重試邏輯
這是接入工作。Studio 仍然可以用來測試模型路徑，但生產迴圈應該放在 API。
一個安全的遷移模式
不要一次把整條工作流搬進 API。
使用這個順序：
- 先在 Studio 手動測試任務
- 寫下穩定的模型、提示詞形狀、輸入檔案和預期結果
- 閱讀 API Models 和模型參考
- 透過 API Quickstart 提交一次生成
- 只有模型需要參考素材時，才加入 Files API
- 輪詢可運作後，才加入 Webhooks
- 只有產品需要在 Studio 之外處理 Chat 回合時，才加入 Chat API
每一步都應該讓工作流更容易營運，而不只是更自動化。
什麼時候留在 Studio
當任務仍然需要以下能力時，留在 Studio：
- 主觀複核
- 提示詞塑形
- 視覺比較
- 模型探索
- 已儲存的創意歷史
- 由人判斷下一步該走圖片、影片、音訊還是 Chat
這不是弱點。Studio 本來就是為這個階段設計的。
什麼時候移到 API
當出現以下條件時，移到 API：
- 同一個任務經常重複
- 輸入可以結構化
- 模型已知
- 應用需要從自己的 UI 建立任務
- 狀態、錯誤和積分可以被清楚處理
- 輪詢或 Webhook 適合產品後端
API 最強的地方，是把已經理解清楚的 Rivya 工作流變成可靠的產品動作。
在 Rivya 的下一步
- 使用 Developers 預覽 API 表面。
- 寫正式產品程式碼前，先讀 Rivya API Quickstart。
- 儲存 API Key 前，先讀 API Authentication。
- 如果下一個問題是如何串接模型、檔案、Chat 和 Webhook，讀 如何用 Rivya API 建立多模態 AI 工作流。
- 如果專案仍然屬於人主導的 Studio 工作，使用 在 Rivya Chat、Image、Video、Audio 之間移動工作。
