Rivya API 是什麼？

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

它不是 Rivya Studio 之外的另一套產品。它沿用相同的帳戶邊界、點數錢包與公開模型目錄。差別只在工作如何開始：你的應用程式不透過 Studio 點選操作，而是使用 API 金鑰發送請求。

如果需要端點細節，請先閱讀 Rivya API 總覽和Rivya API 快速開始。本文從產品角度說明 API 的用途、適合放在哪裡，以及何時不該把它當作第一條路徑。

簡短版本

Rivya API v1 允許符合資格的已登入帳戶建立 API 金鑰，並從網頁介面之外呼叫支援 API 的 Rivya 模型能力。開發者頁面說明目前已實作的介面規格；請求能否實際執行，取決於目前部署、帳號權限與模型就緒狀態。

已實作的 API 能力包括：

• 透過 API 模型清單探索模型

• 非同步圖片、影片和音訊生成任務

• 需要參考媒體的模型可使用 Files API 上傳

• 使用公開任務 ID 輪詢生成狀態

• 檢查帳戶積分

• Chat API 回合，包括選用的 SSE 串流

• 目前部署已啟用 Webhook 時，接收生成完成的簽名事件

• 供需要用戶端封裝的團隊使用的 TypeScript SDK 測試版

公開開發者入口是開發者中心。如果需要導覽式總覽、API 金鑰設定連結與安全除錯流程，從這裡開始最合適。

Rivya 為什麼需要 API

當人還在選模型、調整提示詞、檢視輸出並決定下一步時，Studio 很有用。

當這個決策已經變成可重複的產品或營運工作流程時，API 很有用。

在 API 存取已啟用時，常見例子包括：

• 產品在使用者提交創作簡報後生成圖片變體

• 行銷工作流程需要根據結構化的行銷活動輸入建立視覺草稿

• 內部工具需要提交影片或音訊任務，而不必要求某個人打開瀏覽器

• 支援或內容系統想把一次 Chat 模型回合放進自己的介面

• 後端服務希望在生成任務完成時收到已簽名的回呼

在這些情況下，Rivya API 讓工作維持連接到同一個 Rivya 帳戶，而不是為計費、模型選擇和任務狀態另建一套分離堆疊。

API 不取代什麼

API 不會取代所有直接使用 Rivya 的理由。

遇到以下情況時，請使用 Studio 或公開工作介面：

• 提示詞仍然需要人工探索

• 模型選擇尚未穩定

• 創作者需要以視覺方式比較輸出

• 專案依賴已儲存歷史和人工複核

• 團隊尚未決定哪種輸入與輸出格式應該變成可重複流程

當工作流程清楚到足以自動化時，再使用 API。

這個邊界很重要。模糊的創意問題通常應先放在 Studio。具備可預期輸入的已知產品流程，才適合移到 API。

主要組成

可以把 API 想成六個互相連接的部分。

API 文件才是請求和回應形狀的來源。這篇文章只協助你判斷第一個需要的是哪一部分。

積分如何運作

API 使用量會消耗與 Studio 相同的 Rivya 帳戶積分錢包。

也就是說，API 不是匿名模型代理。每個請求都屬於一個 Rivya 帳戶，使用該帳戶建立的 API 金鑰，並遵循 API 點數中說明的產品層級點數邊界。

這對團隊很有用，因為 Studio 實驗和 API 使用會留在同一個營運模型中。你可以先手動測試模型，再把可重複的部分移進整合流程，而不必建立第二層計費系統。

檔案如何接入

有些模型只靠文字就能執行。其他模型需要參考圖片、影片或音訊檔案。

對 API 整合來說，這些參考素材應該透過 Files API。上傳會建立受管理的檔案記錄，之後可以傳入支援的模型參數。

實務規則很簡單：

• 如果模型接受純文字輸入，先從生成端點開始

• 如果模型需要參考媒體，先上傳檔案

• 如果聊天模型支援圖片附件，請使用 Chat API 與檔案 ID

不要讓整合依賴只能在瀏覽器中使用的上傳流程，也不要依賴已儲存的 Studio 工作階段。API 採用獨立的公開檔案邊界，是為了讓整合流程更明確。

Webhooks 在哪裡有用

輪詢是最容易開始的整合路徑。提交生成任務，儲存公開任務 ID，然後輪詢直到成功或失敗。

如果目前部署已啟用 Webhook，隨著整合逐步走向正式產品流程，它會更有用：

• 你不希望背景工作輪詢每一個任務

• 你的應用程式需要在生成完成時更新一筆記錄

• 你想要一個已簽名、可以安全重試的事件

• 失敗任務需要進入清楚的恢復路徑

簽名事件契約請參考 API Webhooks。圍繞它設計前，請先確認這項功能可用。Webhook 接收端應保持精簡：驗證簽章、處理重複事件，並避免把機密值寫入記錄。

好的第一個 API 專案

最好的第一個 API 專案通常很小，而且很具體。

例如：

1. 確認部署與帳號已啟用 API 存取權限

2. 在設定中建立 API 金鑰

3. 呼叫模型清單

4. 選擇一個支援 API 的模型

5. 使用冪等金鑰提交一個生成任務

6. 輪詢狀態端點

7. 檢查前後點數

8. 之後再加入部署已開放的 Files API、Chat API 或 Webhooks

這條路徑能讓你先取得一個可運作的整合，而不是在第一次測試裡混入所有 API 功能。

什麼時候 API 是錯的起點

在以下情況下，API 很可能不是正確的第一步：

• 團隊尚未選定模型系列

• 期望輸出每次執行都還在變動

• 提示詞依賴人工品味和複核

• 整合會讓需要理解積分使用情況的人看不見消耗

• 產品在自動化前還需要一個公開示範

遇到這些情況，請先從圖片、影片、音訊、聊天或 AI 模型開始。當路徑可以重複時，再把穩定的部分移到 API。

下一步去哪裡

• 打開開發者中心，查看公開 API 入口與除錯工具。

• 閱讀 Rivya API 快速開始，發送第一個安全請求。

• 將金鑰放到伺服器前，先閱讀 API 驗證。

• 選擇模型 ID 前，先閱讀 API 模型。

• 如果產品邊界仍不清楚，讀 什麼時候該用 Rivya API 而不是 Studio。

• 規劃完整的圖片、影片、音訊或聊天整合時，請閱讀如何用 Rivya API 建置多模態 AI 工作流程。