上線檢查清單

示範只需要一個請求，產品卻要撐得住逾時、重複的 Webhook、過期的連結，以及外洩的金鑰。上線前請把這份清單走過一遍。

金鑰

• 金鑰放在伺服器的機密管理中，絕不放進瀏覽器或 App 套件。
• 每個環境、每個服務各用一把金鑰，可以單獨撤銷。
• 正式環境的金鑰只允許呼叫你用到的模型，並設有每日消費上限。
• 你知道如何不中斷服務地輪替金鑰（驗證）。

建立任務

• 每次 createTask 都帶 Idempotency-Key，從你自己的工作 ID 推導，只產生一次，每次重試都沿用。
• 只重試 429、500、503 與 50301，並搭配退避、遵守 Retry-After（錯誤碼）。
• 400、40004 這類「得改請求」的錯誤會顯示或記錄下來，而不是重試。
• 如果會顯示價格，先報價，再傳入 quoteId 與 expectedCredits，並處理 40901。
• 餘額不足（40201）會在使用者察覺之前通知到人——告警、Email 或橫幅都可以。

取得結果

• 任務帶有 callBackUrl；你的端點會驗證簽章並拒絕過期的時間戳記。
• Webhook 處理程式會快速回傳 2xx，把工作交給背景處理。
• 依 request_id 忽略重複送達。
• 有定期程序補讀沒收到 Webhook 的任務。
• 程式把 succeeded、failed、expired、canceled 以外的任何狀態都視為「仍在執行」。

檔案

• 完成的檔案會複製到你自己的儲存空間（或素材庫），而不是直接引用約 20 分鐘後過期的簽名連結。
• 你儲存的是 taskId，不是簽名連結。
• 下載程式不會把 API 金鑰送給簽名連結。
• 參考檔案是直接指向檔案的公開 HTTPS 連結、上傳檔案或素材——不是分享頁面。

費用

• 你清楚每個模型的計價單位（每張、每秒、每次），以及哪些設定會讓價格變高。
• 預覽與測試使用最便宜的解析度與最短的長度。
• 設好消費上限，能在失控的迴圈花光餘額前擋下來。
• 你會檢查 credits 與 settled，而不是假設扣掉的就是預估金額。

監控

• 每次失敗都記錄 request_id、taskId、code 與 errorCode。
• 你會依模型觀察 failed 任務的比例；突然升高通常代表提示詞、輸入或模型有所變動。
• 你會依模型追蹤從 createTask 到收到 Webhook 的時間，並對異常值告警。
• 團隊中有人知道 API 控制台的記錄頁與用量頁在哪裡。

內容

PopNow 是面向大眾的服務。模型有各自的內容規則，被拒絕的請求會以 content_rejected 失敗。如果提示詞由你的使用者撰寫，請在你自己的介面中說明請求被拒絕的原因並讓他們修改，而不是直接顯示原始錯誤。