用 Rivya API 接入多模態工作流程

一條好的 Rivya API 接入，不只是向某個模型送出一次請求。

真實產品流程通常是一條小鏈路：選擇合適模型、準備輸入、需要時上傳參考檔案、提交任務、追蹤狀態、處理積分，並在結果準備好後通知產品裡的正確位置。

本文說明如何規劃整體流程。最短的可執行路徑請參考 Rivya API 快速開始，確切的請求欄位請以 API 文件為準。

下文說明的是已實作的公開 API 規格。開始開發前，請先確認目前部署與帳號都已啟用公開 API、所選模型支援 API 呼叫，並核實 Webhook 等選用功能確實可用。

先定義產品時刻

選擇端點前，先用一句話描述產品中的使用情境。

例如：

• 賣家提交商品頁需求後，建立一版產品圖片草稿。

• 行銷活動負責人核准靜態方向後，生成一版短影片概念。

• 在內部研究工具裡送出一輪 Chat 對話，並將串流回覆傳回給使用者。

• 上傳參考圖片，提交支援該輸入的模型請求，並在結果完成時通知使用者。

這句話可以避免接入變成一組鬆散的 API 呼叫。

寫程式前先對應工作流程

開啟請求結構描述前，先參考這張表。

工作流程應該清楚到每個 API 區域都有存在理由。

第 1 步：為這項整合建立金鑰

為實際使用它的應用程式、環境或工作流程建立 API 金鑰。

避免用同一把金鑰處理所有事情。請依用途命名，方便日後審核：

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• webhook-smoke-test

儲存金鑰前請先閱讀 API 驗證。完整金鑰只會顯示一次，團隊應立即把它存入正確的伺服器端金鑰儲存空間。

第 2 步：從公開 API 列表選模型

不要只因為某個模型在手動測試中可用，就直接把它寫死在產品裡。

使用 API 模型和模型 API 參考確認：

• 公開模型 ID

• 是否可透過 API 使用

• 支援的輸入模式

• 提示詞與參數要求

• 是否需要 Files API

• 點數行為與就緒狀態說明

許多整合會在這一步變得更清楚。適合在 Studio 手動測試的模型，不一定是自動化產品流程的最佳首選。

第 3 步：決定第一版是否包含 Files API

如果模型只用文字輸入就能執行，第一版就先維持純文字流程。

只有當工作流程真的需要參考媒體時，才加入 Files API。

加入時，先定義：

• 產品接受哪些檔案種類

• 誰負責檔案清理步驟

• 上傳失敗時會發生什麼

• 回傳的檔案資料如何傳入模型參數

• 同一個檔案應該重複使用，還是重新上傳

這可以避免把不穩定的檔案流程藏在看似簡單的生成按鈕後面。

第 4 步：提交生成任務

對圖片、影片和音訊生成，正常模式是：

1. 準備模型 ID、提示詞與支援的 params

2. 加上冪等金鑰，以便安全重試

3. 透過生成端點提交

4. 儲存公開任務 ID

5. 輪詢狀態，直到任務進入最終狀態

請在建立生成任務查看請求格式，並依生成狀態處理結果。

產品應該把 queued、processing、succeeded 和 failed 視為使用者可見狀態。不要讓使用者閱讀系統細節，也不要讓他們猜測任務為什麼慢。

第 5 步：Chat 模型使用 Chat API

聊天模型應使用 Chat API，而不是生成端點。

這很重要，因為 chat 工作有不同的行為：

• 每輪聊天可以隸屬於由 API 建立的工作階段

• 非串流與 SSE 串流帶來不同的使用體驗

• 圖片附件使用 Files API 的檔案 ID

• 點數按聊天回合結算，而不是依一般非同步媒體任務結算

如果產品需要在自有介面中提供助理回答，Chat API 可能是正確路徑。如果使用者仍在探索想法，Rivya Chat 或 Studio 可能更合適。

第 6 步：先輪詢，再加入 Webhook

第一版使用輪詢，整體流程會更容易理解與除錯。

如果目前部署已啟用 Webhook，可在以下情況加入 API Webhooks：

• 產品有許多非同步任務

• 等待中的用戶端不應持續自行輪詢

• 下游系統需要已簽名的完成事件

• 已設計好重試與重複事件處理

Webhook 接收端應保持單純而嚴格：驗證簽章、以可安全處理重複事件的方式接收資料、更新一筆產品記錄，並且只留下可安全記錄的內容。

第 7 步：讓產品看得懂積分

Rivya API 使用與 Studio 相同的帳戶積分。

你的接入應該決定要顯示多少資訊。至少團隊應該知道：

• 哪個帳戶擁有 API 金鑰

• 哪個工作流程可能消耗點數

• 積分過低時會發生什麼

• 如何說明生成失敗狀態

• 使用者應該去哪裡詢問積分與帳單問題

請閱讀 API 點數、Rivya 點數與帳單和如何理解 Rivya 點數、點數包與方案，了解使用者看到的點數機制。

一個小而穩的第一版

好的第一版會刻意限制範圍。

例如：

1. 一把 API 金鑰

2. 一個已選定的圖片模型

3. 暫時不加入檔案上傳

4. 一個生成請求

5. 一條狀態輪詢路徑

6. 產品中的簡單結果預覽

7. 一則清楚的點數錯誤訊息

這個版本先證明連線成立，再增加更多移動部件。

更完整的版本

第一版可用之後，更完整的工作流程可以加入：

• 用於參考圖片或影片的 Files API

• 模型專屬參數控制

• 與產品記錄綁定的冪等性處理

• 功能已啟用時，用簽名 Webhook 接收完成事件

• 用於助理對話的 Chat API

• 聊天需要即時輸出時使用的伺服器端事件串流

• 供管理員或客服查看失敗任務的介面

每個新增項目都應回應真實產品需求。如果只是為了讓示範看起來更龐大，應暫緩加入。

常見接入錯誤

避免這些模式：

• 一開始就使用所有 API 功能

• 對帳戶擁有者隱藏點數用量

• 在 API 流程中套用只能在 Studio 成立的假設

• 把檔案上傳視為事後才補的細節

• 重試生成請求時未使用冪等性機制

• 對應為非同步生成的任務使用 Chat API

• 對聊天回合使用生成端點

• 記錄完整 API 金鑰、Webhook 金鑰或暫存檔案細節

最安全的 API 工作流程會清楚界定擁有權、狀態與失敗處理方式。

下一步

• 從開發者中心進入公開 API 入口。

• 使用 Rivya API 快速開始執行第一個請求。

• 選擇模型 ID 前，先查看 API 模型。

• 只有模型確實需要參考媒體時，才使用 Files API。

• 使用 Chat API處理聊天回合與串流聊天回覆。

• 輪詢已不敷使用，而且 Webhook 存取權限已啟用時，再使用 API Webhooks。

• 如果工作流程仍需要人工探索，請先閱讀何時應使用 Rivya API，而不是 Studio，再將它自動化。