疑難排解

找到對應的症狀，照著修正。如果這裡都幫不上忙，請附上 request_id 聯絡客服。

第一次呼叫就失敗

401「Missing credentials」。 Authorization 標頭沒有送達。檢查執行請求的 shell 或程序中是否設定了環境變數（echo ${POPNOW_API_KEY:0:10} 應顯示 sk-popnow-），以及代理或 HTTP 函式庫是否把標頭丟掉了。

401「Key format is not recognized」。 這個值不是 PopNow 的金鑰——常是剪貼簿裡的其他內容。金鑰以 sk-popnow- 開頭。

401「Credentials are invalid or expired」。 金鑰已撤銷、過期或輸入錯誤。請在 API 控制台建立新的。

40310。 帳戶的電子郵件尚未驗證。開啟註冊信中的連結，金鑰會立即可用。

40201「Insufficient balance」。 帳戶的點數不足以保留這個任務的金額。影片的保留額可能較大；先用 jobs/quote 確認價格，再購買點數。

請求被拒絕

400 並指出某個欄位。 input 不符合模型的 schema：欄位名稱拼錯、值不在允許清單中，或缺少必填欄位。從模型開啟該模型的參考頁比對。

400「Invalid callback URL」。 callBackUrl 必須是公開的 HTTPS 網址、使用 443 連接埠，且不含使用者名稱或密碼。localhost 與內網位址都會被拒絕。

40004。 模型正常，但目前無法處理這組設定。修改 msg 指出的設定（常是解析度、長度或長寬比）。

50301。 模型暫時無法接受任務。稍後再試或換一個模型。

413。 JSON 請求內容超過 2 MiB，通常是因為內嵌圖片。請改用上傳。

任務失敗

invalid_asset。 參考檔案無法下載或讀取。在瀏覽器無痕視窗開啟該網址：它必須直接下載檔案本身，且不需登入。雲端硬碟的分享頁不行。

content_rejected。 模型拒絕了提示詞或參考圖。換個說法、換參考素材，或換一個模型。

timeout 或 expired。 任務花的時間超過上限。試試更短的長度或更低的解析度。

generation_failed。 模型執行了但沒有產出。同樣的輸入常會再次失敗；請修改提示詞或設定。

失敗與過期的任務都不會扣點數。

結果

下載連結回傳 403 或「expired」。 簽名連結約 20 分鐘有效。用 recordInfo 重新讀取任務，取得新連結。

帶上 API 金鑰後下載連結反而失敗。 不要對簽名連結送出 Authorization；連結本身就是授權。

我建立的任務 recordInfo 卻回傳 404。 任務只對建立它的金鑰可見。請用同一把金鑰，或在 API 控制台查詢。

Webhook

什麼都沒收到。 確認網址能從網際網路透過 HTTPS 連線、防火牆有放行，且處理程式會在 15 秒內回傳 2xx。送達失敗的紀錄可在 API 控制台查看。

簽章一直不相符。 對原始請求內容的位元組做雜湊，而不是重新序列化的 JSON；使用 data.taskId、X-Webhook-Timestamp 標頭，以及你最近產生的密鑰。

同一個任務收到兩次。 重試後這是正常的。依 request_id 忽略重複。

上傳

PUT 被儲存空間回傳 403。 某個標頭與票證不一致。請原樣送出 Content-Type 與 Content-Length，且不要帶 Authorization 標頭。

提交回傳 40003。 上傳的檔案與你宣告的不符。請以正確的 contentType 與 bytes 重新申請票證。

提交回傳 409。 票證已過期（約 20 分鐘）。請在上傳前一刻再申請。