影片任務流程

PopGo 影片生成採用非同步任務。提交後保存任務 ID，輪詢狀態，完成後下載結果。

Endpoint

POST https://api.popgo.site/v1/videos
GET  https://api.popgo.site/v1/videos/{task_id}
GET  https://api.popgo.site/v1/videos/{task_id}/content
Authorization: Bearer YOUR_API_KEY

欄位	類型	說明
`model`	string	必填，公開模型 ID
`prompt`	string	必填，場景、動作、鏡頭與聲音描述
`duration` / `seconds`	integer	只能使用模型允許的值
`resolution`	string	模型允許的解析度
`aspect_ratio`	string	模型允許的比例
參考欄位	array / string	依模型頁使用圖片、影片或音訊

curl -X POST https://api.popgo.site/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL","prompt":"A bamboo forest in morning mist, slow forward camera movement","seconds":5,"resolution":"480p","aspect_ratio":"16:9"}'

輪詢與進度

狀態通常為 queued、in_progress、completed、failed。若回應有 progress，可顯示百分比；沒有時只顯示處理中，不要自行偽造數字。完成後讀取 URL 或呼叫 /content 下載。

curl https://api.popgo.site/v1/videos/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

HTTP 400 檢查模型、欄位類型、時長、解析度、比例與參考數量；401/403 檢查 Key 與權限。影片計費可能按任務、秒數或規格，請以模型頁為準。

輪詢、逾時與重試範圍

建立只送一次，立即保存id、模型、時長、解析度及模式。建立逾時可能發生於已接受之後，先查任務紀錄再重送。對同一id重試查詢或下載不會另建影片。

一般3–5秒，C為10–15秒，Kling可10秒並預留至少15分鐘。429/502/503及暫時網路錯誤採有限退避並遵循Retry-After。400先改參數，401/403先處理驗證或權限。達到用戶端期限時標示等待逾時並保留任務，不冒稱服務失敗。

progress可能長期0後直接100或缺少；model、usage、解析度、實際時長及fps亦可能缺少。保留提交參數並檢查下載媒體；無usage不代表免費。queued/in_progress不是失敗，completed才下載。

結果URL可過期或需驗證，優先用PopGo的/content。完成後內容暫不可用則有限重試下載，不另建任務。大檔需足夠下載時間，確認是影片而非JSON錯誤頁。不要向第三方素材主機傳送PopGo API Key。

分清五個排錯階段

階段	可證明	不可推斷
介面驗證	本機模式、數量及來源是否接受	沒有請求不代表服務拒絕
PopGo解析與能力驗證	400/500是否發生於建立前	服務無紀錄不必然是供應商故障
實際發出載荷	圖片／影片／音訊欄位及角色	正確欄位不保證可抓取素材
任務接受與輪詢	id、狀態與失敗階段	200或id不證明使用素材或免費
完成媒體	畫面、主體、動作及声音是否採用素材	下載URL不證明品質

記錄脫敏模型、時間、任務id佔位符、模式、素材數量／來源及錯誤摘要。不得附Key、Cookie、簽名URL或私人素材。容量與內容審核分別處理；失敗亦需核對帳單。修正已知原因後再承擔新生成費用。

Endpoint​

輪詢與進度​

輪詢、逾時與重試範圍​

分清五個排錯階段​

Endpoint

輪詢與進度

輪詢、逾時與重試範圍

分清五個排錯階段