U9 AI · INSIGHTS
影片 API 串接：從受控測試到可下載結果
使用 U9AI 的公開模型資訊、單次受控測試、非同步任務查詢與結果取得，降低影片 API 串接風險。
先說結論#
影片串接應被視為非同步流程，而不是一次請求。先確認已啟用模型與其協定，再送出一次範圍明確的小型測試；保留請求或任務識別碼，查詢至終態，再從文件規定的結果欄位取得資源。目錄中看得到模型，並不代表每個參數、帳戶或協定都可用。
1. 先定義一個可驗證的結果#
請求前寫下這次測試要驗證的結果：輸入類型、預期比例或時長、是否需要音訊，以及成片要交付到哪裡。首測範圍越小越好。同一份已知輸入、一個預期結果，比同時改動多個變數更容易排查。
面向使用者的流程也要先定義任務執行時顯示什麼：等待狀態、安全的重試提示，以及完成後仍可存取的結果區域。請求被接受，不等於結果已成功生成。
2. 分開確認模型與契約#
先查看模型目錄與 API 位址、協定與模型選擇。確認帳戶可見的模型識別碼、生成方式及該設定使用的協定；再依單模型公開契約確認建立欄位、狀態值與結果欄位。
這項區分很重要：模型可以在目錄中展示，但某個工具、帳戶權限、輸入形式或可選參數未必相容。契約不完整時，不要猜測端點，也不要靜默改用其他模型。
3. 為首次付費測試設邊界#
只提交有權使用的輸入。選擇能回答問題的最小設定，設定單次嘗試預算，並在提交前記錄顯示價格。將請求 ID、任務 ID 與所選設定一起儲存到自己的紀錄中。
若請求逾時，但它可能已到達上游，應把提交狀態標記為未知，並依識別碼排查。非同步付費請求不能盲目重送，否則可能產生重複任務與重複扣款。
4. 查詢到任務終態#
影片任務通常不會在建立呼叫中完成。只使用公開契約規定的查詢方式，以適度間隔和有限逾時查詢狀態；保留上游狀態與錯誤碼。終態失敗是有價值的工單證據，連續重複提交不是解法。
任務完成後，再讀取約定的輸出 URL 或媒體欄位。任務完成與資源可下載是兩次檢查，應用程式應清楚顯示下載失敗，而不能把它掩蓋成生成失敗。
5. 讓結果可用且可追溯#
返回媒體格式支援時，顯示預覽和直接資源操作。只保存產品確實需要的引用與紀錄；不要在公開日誌暴露 API 金鑰、提示詞或私有素材。每次測試保留模型、參數、請求或任務 ID、時間、終態，以及可解釋扣款的請求/餘額紀錄。
Seedance V2 的公開流程請查看 Seedance 2.0 V2 影片 API；通用核對可看模型測試指南。若公開契約與實際回應不一致，帶上識別碼和已去識別回應片段提交私人工單，不要傳送金鑰。