# API 請求逾時時，如何避免重複的影片工作？ > 為每個目標輸出分配穩定的操作鍵，在傳送前持久化請求，在可用時使用供應商文件明確支援的冪等機制，並在重試前核對結果不明的逾時。逾時代表結果未知，而不是供應商已拒絕工作。 # API 請求逾時時，如何避免重複的影片工作？ 提交逾時會產生歧義結果。請求可能在到達服務前失敗，可能已到達但被拒絕，也可能已建立遠端影片工作，只是回應沒有傳回用戶端。因此立即重試，可能把一支預期影片變成兩次付費生成。 解決方案是在影片 API 外圍建立冪等操作層。先建立並持久化預期操作，為它提供穩定鍵，記錄每次嘗試，並使用供應商文件明確支援的冪等或查詢能力。如果無法證明遠端結果，就把操作放入明確的未知狀態，而不是假設它已失敗。 ## 定義一個預期副作用 冪等鍵必須識別使用者要求系統建立的內容，而不能識別某一次 HTTP 嘗試。如果每次重試都取得新鍵，供應商就無法辨識重複請求。 在目錄工作流程中，一次操作可由以下內容定義： * 產品 ID； * 創意範本版本； * 來源媒體指紋； * 提示詞版本； * locale； * 長寬比； * 變體名稱。 建立鍵順序固定、值已正規化的標準表示，再計算雜湊。將可讀維度與雜湊一同儲存。當使用者有意請求另一次獨立生成時，即使提示詞相同，也應建立新操作或新變體。 不要在重試迴圈內產生隨機 UUID。操作鍵必須在第一次請求前建立，並持續重複使用，直到該預期副作用進入終止狀態。 ## 傳送前先持久化 網路呼叫開始前，本機資料庫就應知道這次操作。這是把預寫原則套用到 API 副作用。 操作記錄可以包含： | 欄位 | 作用 | |---|---| | 操作鍵 | 防止重複本機意圖 | | 請求雜湊 | 證明提交了哪些參數 | | 狀態 | 區分已準備、已傳送、未知和已完成 | | 嘗試次數 | 套用有上限的重試策略 | | 供應商與模型 | 支援路由和核對 | | 遠端工作 ID | 不必重新提交即可恢復輪詢 | | 最近錯誤 | 保留診斷脈絡 | | 輸出校驗和 | 發現重複或變化的資產 | 對操作鍵使用資料庫唯一限制。兩個 worker 同時建立同一操作時，應匯聚到同一筆記錄。任何 worker 在傳送請求前，都應透過不可分割更新或租約領取該記錄。 ## 只依供應商文件使用冪等機制 有些 API 接受冪等鍵或請求權杖，並在相同鍵重複使用時傳回第一次已接受請求的結果。當文件明確涵蓋端點、保留期限、參數比較方式和錯誤行為時，這是最可靠的路徑。 需要核對四項細節： * 影片生成端點是否支援該鍵； * 供應商會記住它多久； * 相同鍵搭配不同參數時是否會被拒絕； * 重試是否傳回原本的遠端工作 ID。 不要假設付款介面或同步文字請求支援的 header 也適用於非同步影片工作。OpenAI 相容的請求形狀，不會自動讓供應商特定的工作建立具備冪等性。 ## 將逾時視為未知結果 狀態應描述證據，而不是主觀希望。 | 狀態 | 證據 | 下一步 | |---|---|---| | `prepared` | 本機記錄存在，尚未傳送 | 提交 | | `sending` | Worker 已開始請求 | 等待結果或逾時 | | `accepted` | 已收到遠端工作 ID | 輪詢 | | `unknown` | 發生逾時且無確認結果 | 核對 | | `failed` | 供應商明確拒絕或結束工作 | 套用失敗策略 | | `complete` | 輸出已持久儲存 | 傳回現有結果 | `unknown` 與 `failed` 的差異至關重要。網路例外是用戶端連線的證據，不一定說明供應商端發生了什麼。 如果 API 提供用戶端參照或中繼資料物件，應將本機操作鍵附加到供應商中繼資料。這樣，後續清單查詢或支援請求就有穩定識別可搜尋。 ## 重試前先核對 核對 worker 負責調查未知操作。可用證據取決於供應商，但順序應明確。 1. 檢查原始嘗試是否在程序失敗前儲存了遠端工作 ID。 2. 若支援，依冪等鍵或用戶端參照查詢供應商。 3. 使用建立時間、模型和請求指紋搜尋有限範圍的工作清單。 4. 檢查用戶端逾時後可能到達的 webhook 事件。 5. 當帳單或用量事件出現得夠快，也可進行比較。 6. 只有能證明不存在工作，或文件保證冪等重試安全時，才重新傳送。 僅依時間與提示詞匹配可能產生誤判。應結合多個屬性，並把不確定匹配送交人工審核。如果 API 不提供查詢能力，也沒有冪等保證，正確策略可能是等待、接受潛在重複，或依短片成本與期限要求人工決定。 ## 區分傳輸重試與操作重試 HTTP 函式庫經常自動重試網路錯誤。這對安全讀取有幫助，但對有副作用的提交很危險。除非操作受穩定冪等鍵保護，且端點文件明確支援，否則應停用通用 POST 重試。 使用兩個計數器： * 傳輸嘗試次數，用於傳送同一個受保護操作； * 生成嘗試次數，用於終止失敗或品質拒絕後，有意建立替代輸出。 兩者代表不同成本。傳輸重試應匯聚到同一個遠端工作；生成重試則是新的計費創意嘗試，需要新的嘗試識別，但仍要連接到原本的製作工作。 ## 使用租約處理並行 worker 逾時不是重複的唯一來源。兩個 worker 可能領取同一個佇列項目，或者較慢的 worker 在租約到期後仍繼續執行。 透過包含擁有者、領取時間和到期時間的不可分割租約來認領工作。提交前，worker 要確認自己仍持有租約，且記錄中不存在已接受的遠端工作。儲存遠端工作 ID 時使用交易或比較後交換更新，如果另一個 worker 已推進狀態，更新就會失敗。 當舊 worker 仍可能寫入時，使用 fencing token。每次領取租約都遞增版本號，資料庫只接受最新版本的狀態變更，避免舊程序覆寫較新的結果。 ## 讓 webhook 與輪詢匯聚 影片工作是非同步的，因此輪詢和 webhook 可能回報同一個狀態轉換。相應的處理器也必須具備冪等性。 如果供應商有事件 ID，就依事件 ID 去重。同時讓狀態更新附帶條件：回報 `processing` 的事件不能把已經 `complete` 的工作倒退。重複下載同一輸出時，應寫入確定性的暫存鍵、驗證校驗和，並匯聚到一個最終持久物件。 成功完成路徑應可安全重複： ```text 接收完成事件 依遠端工作 ID 查找操作 將輸出複製到確定性儲存鍵 驗證媒體與校驗和 記錄持久 URI 若尚未完成則將操作標記為完成 ``` 任何一步當機，下一個處理器都能恢復，而不必生成新影片。 ## 記錄足夠證據以稽核重複工作 為每次嘗試保留傳送前後時間戳記、逾時類型、請求雜湊、冪等鍵、供應商回應 header、遠端 ID 和重試決定。憑證與敏感提示詞資料必須去識別化。 追蹤以下營運指標： | 指標 | 能揭露的問題 | |---|---| | 未知提交 | 網路或供應商歧義 | | 未經重試即核對成功 | 已成功避免的重複工作 | | 受保護重試次數 | 故障時的冪等行為 | | 疑似重複工作 | 剩餘財務風險 | | 重複輸出校驗和 | 相同或重複的供應商結果 | | 未知狀態停留時間 | 復原速度 | 未知結果異常增加時應發出警示，而不是直接提高重試上限。網路退化與激進重試同時發生，會快速放大成本。 ## 將供應商行為封裝在介面卡中 多模型應用程式應提供一個包含供應商能力旗標的內部提交介面。介面卡負責端點 schema、冪等機制、工作查詢、狀態映射和輸出擷取。 對於透過一個 OpenAI 相容平台使用文字、圖像與影片模型的團隊，[Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=avoid-duplicate-video-jobs-api-timeout) 可以減少整合工作。但仍要核對目前影片模型與端點的具體行為。相容性可正規化許多請求模式，但不應被視為非同步工作冪等性的統一保證。 介面卡應傳回正規化結果，例如已接受並附遠端 ID、明確拒絕或結果未知。不要在介面卡內把傳輸例外折疊成供應商失敗。 ## 主動測試歧義情境 正常路徑無法證明重複安全性。在預備環境中，分別在傳送前、位元組離開用戶端後、供應商接受後、收到回應但資料庫更新前，以及 webhook 傳遞期間注入故障。 對每種情況，當供應商支援冪等性時，應斷言一個預期操作最多產生一個遠端工作。如果不支援，則應斷言操作進入 `unknown`、暫停自動重新提交，並提供足夠證據以執行既定政策。 還要測試並行 worker、到期租約、延遲 webhook、重複 webhook、程序重新啟動，以及使用舊鍵搭配改變的參數。這些測試比在帳單中發現重複生成便宜得多。 ## 結論 要避免重複影片工作，應為每個目標輸出提供一個持久操作鍵，並將該操作與 HTTP 嘗試分開。傳送前儲存意圖，使用文件明確支援的供應商冪等機制，並把逾時視為需要核對的未知結果。藉助租約、條件式狀態變更、冪等完成處理器和持久嘗試日誌，重試才會成為受控復原，而不是意外重複購買。 ## FAQ ### HTTP 逾時是否代表影片 API 沒有建立工作？ 不是。供應商可能已接受請求並建立工作，只是用戶端沒有收到回應。在完成核對前，應將結果視為未知。 ### 冪等鍵應該代表什麼？ 它應代表一次預期副作用，例如某個產品、範本版本、locale、長寬比和變體。對該操作的重試應重複使用此鍵，但真正的新輸出應使用新鍵。 ### 資料庫唯一限制能防止所有重複嗎？ 它能防止重複的本機操作，但本身無法阻止供應商接受兩次請求。應將它與供應商冪等機制或核對流程搭配使用。 ### 用戶端是否應該自動重試每一次逾時？ 不應該。只有當請求具備冪等性，或能確定供應商端結果時，自動重試才安全。否則應把工作置於未知狀態並先核對。 ### 冪等記錄應該保留多久？ 至少保留到重試窗口、供應商查詢窗口、帳單爭議窗口和營運稽核需求全部結束。具體期限應符合供應商文件和業務風險。 ### OpenAI 相容 API 是否保證不同影片模型具有相同的冪等行為？ 不保證。相容性可以統一傳輸方式，但非同步工作建立和冪等支援仍可能依模型或供應商而異。請核對目前端點文件。