一條好的 Rivya API 接入，不只是向某個模型送出一次請求。
真實產品流程通常是一條小鏈路：選擇合適模型、準備輸入、需要時上傳參考檔案、提交任務、追蹤狀態、處理積分，並在結果準備好後通知產品裡的正確位置。
這篇文章說明規劃形狀。最短可執行路徑請看 Rivya API Quickstart，精確請求欄位請以 API 文件為準。
先定義產品時刻
選擇 endpoint 之前，先用一句話描述產品時刻。
例如：
賣家提交 listing brief 後，建立一版產品圖片草稿。campaign manager 核准靜態方向後，生成一版短影片概念。在內部研究工具裡送出一輪 Chat turn，並將 streaming 回覆傳回給使用者。上傳參考圖片，提交支援該輸入的模型請求，並在結果完成時通知使用者。
這句話可以避免接入變成一組鬆散的 API 呼叫。
寫程式前先對應工作流
打開 request schema 之前，先用這張表。
| 工作流步驟 | 產品問題 | API 區域 |
|---|---|---|
| 帳戶存取 | 哪個 Rivya 帳戶擁有這次使用量？ | API Authentication |
| 模型選擇 | 哪個公開 model ID 適合這件工作？ | API Models |
| 參考輸入 | 模型是否需要上傳媒體？ | Files API |
| 生成 | 這是非同步圖片、影片還是音訊任務？ | Create Generation |
| Chat | 這是 chat model turn，而不是 generation job 嗎？ | Chat API |
| 狀態 | 產品要如何知道結果已準備好？ | Generation Status |
| 完成事件 | 另一個系統是否應接收簽名 callback？ | API Webhooks |
| 積分 | 團隊要如何理解成本？ | API Credits |
工作流應該清楚到每個 API 區域都有存在理由。
第 1 步：為這個接入建立 Key
為會使用它的具體 app、環境或工作流建立 API key。
避免一把 key 用於所有事情。依用途命名 key，之後審核會更容易：
production-image-workflowstaging-video-testsinternal-chat-assistantwebhook-smoke-test
儲存 key 前先閱讀 API Authentication。完整 secret 只會顯示一次，所以團隊應立即將它存到正確的 server-side secret store。
第 2 步：從公開 API 列表選模型
不要只因為某個 model 在手動測試裡可用，就直接把它 hard-code 進產品。
使用 API Models 和 Model API Reference 確認：
- 公開 model ID
- 是否可透過 API 使用
- 支援的輸入模式
- prompt 與參數預期
- 是否需要 Files API
- 積分行為與 readiness notes
很多接入會在這一步變得更清楚。很適合手動 Studio 測試的 model，不一定是自動化產品流程的第一個正確 model。
第 3 步：決定第一版是否包含 Files API
如果 model 可以只用文字輸入執行，第一版就保持 text-only。
只有當工作流真的需要參考媒體時，才加入 Files API。
加入時，先定義：
- 產品接受哪些檔案種類
- 誰負責檔案清理步驟
- 上傳失敗時會發生什麼
- 回傳的 file data 如何傳入模型參數
- 同一個檔案應該重複使用，還是重新上傳
這可以避免脆弱的檔案體驗被藏在看似乾淨的 generate button 後面。
第 4 步：提交一個 Generation Job
對圖片、影片和音訊生成，正常模式是：
- 準備 model ID、prompt 和支援的 params
- 加上 idempotency key 以便安全重試
- 透過 generation endpoint 提交
- 保存 public task ID
- 輪詢狀態，直到 task 進入 terminal state
請使用 Create Generation 查看請求形狀，使用 Generation Status 處理結果。
產品應該把 queued、processing、succeeded 和 failed 視為使用者可見狀態。不要讓使用者閱讀系統細節，也不要讓他們猜測任務為什麼慢。
第 5 步：Chat 模型使用 Chat API
Chat 模型應使用 Chat API，而不是 generation endpoint。
這很重要，因為 chat 工作有不同的行為：
- chat turns 可以屬於 API 建立的 sessions
- non-streaming 和 SSE streaming 有不同的使用者體驗
- 圖片附件使用 Files API 的 file IDs
- 積分結算跟隨 chat turn，而不是一般非同步媒體任務
如果你的產品需要在自己的介面裡提供 assistant answer，Chat API 可能是正確路徑。如果使用者仍在探索想法，Rivya Chat 或 Studio 可能更合適。
第 6 步：先用 Polling，再加入 Webhooks
第一版用 polling 更容易推理。
符合以下情況時，再加入 API Webhooks：
- 產品有許多非同步任務
- 等待中的 clients 不應直接 polling
- 下游系統需要 signed completion events
- retry 和 duplicate handling 已經設計好
Webhook receiver 應該單純且嚴格：驗證 signature、接受 duplicate-safe events、更新一筆產品記錄，並且只記錄安全可記錄的內容。
第 7 步：讓產品看得懂積分
Rivya API 使用與 Studio 相同的帳戶積分。
你的接入應該決定要顯示多少資訊。至少團隊應該知道：
- 哪個帳戶擁有 API key
- 哪個 workflow 可能消耗積分
- 積分過低時會發生什麼
- generation failed state 如何說明
- 使用者應該去哪裡詢問積分與帳單問題
請使用 API Credits、Credits & Billing in Rivya 和 How to Think About Rivya Credits, Packs, and Plans 理解使用者可見的 wallet model。
一個小而穩的第一版
好的第一版會刻意限制範圍。
例如：
- 一把 API key
- 一個已選定的 image model
- 暫時沒有 file upload
- 一個 generation request
- 一條 status polling path
- 產品裡一個簡單 result preview
- 一則清楚的 credit error message
這個版本先證明連線成立，再增加更多移動部件。
更完整的版本
第一版可用之後，更完整的工作流可以加入：
- 用於 reference images 或 videos 的 Files API
- model-specific parameter controls
- 與你的 product record 綁定的 idempotency
- 用於 completion 的 signed webhooks
- 用於 assistant turns 的 Chat API
- chat 需要 live output 時的 server-side event stream
- 給 admin 或 support 查看 failed jobs 的視圖
每個新增項目都應回應真實產品需求。如果它只是讓 demo 看起來更大，先不要加。
常見接入錯誤
避免這些模式：
- 一開始就使用每個 API feature
- 對帳戶 owner 隱藏 credit usage
- 在 API flow 裡使用 Studio-only assumptions
- 把 file uploads 當成事後補上的細節
- retry generation requests 時沒有 idempotency
- 對應該是 async generation 的 jobs 使用 Chat API
- 對 chat turns 使用 generation endpoints
- 記錄完整 API keys、webhook secrets 或 temporary file details
最安全的 API 工作流，會明確說清楚 ownership、state 和 failure handling。
下一步
- 從 Developers 進入 public API hub。
- 使用 Rivya API Quickstart 執行第一個 request。
- 選擇 model IDs 前，先使用 API Models。
- 只有當 model 真的需要 reference media 時，才使用 Files API。
- 使用 Chat API 處理 chat turns 和 streaming chat responses。
- 當 polling 已經不夠時，使用 API Webhooks。
- 如果 workflow 仍需要人工探索，先閱讀 When to Use Rivya API Instead of Studio，再自動化它。
