·5 分鐘閱讀
AI 影片生成 API 教學:提交、輪詢與下載影片

直接答案:AI 影片生成 API 通常是非同步工作流程,不是一次請求就回傳 MP4。先提交影片任務、保存回傳的 task ID、查詢狀態直到 completed 或 failed,再下載結果。TokAtlas 對應三個步驟:POST /v1/videos、GET /v1/videos/{id} 與 GET /v1/videos/{id}/content。
AI 影片生成 API 的正確流程
- 提交:呼叫 POST /v1/videos,傳入已在帳戶啟用的模型 ID、prompt 與支援設定;立即保存回傳的 id。
- 查詢:以 GET /v1/videos/{id} 輪詢。queued 與 in_progress 都是等待中的狀態,不代表生成完成。
- 下載:只有 status=completed 才能呼叫 GET /v1/videos/{id}/content 取得 MP4;若是 failed,請保留錯誤與任務 ID。
這個工作流適用於文字轉影片 API、圖片轉影片 API、非同步影片任務、輪詢影片生成狀態與下載 AI 影片等整合場景。成功的 POST 只表示平台已接受任務,不代表影片已準備好。
開始前:模型、金鑰與可重現記錄
- 建立 TokAtlas API Key,僅存放在後端環境變數,絕不放進前端或行動 App。
- 確認精確模型 ID 已在帳戶啟用,而且支援 /v1/videos 及所需的長度、比例、解析度和參考素材。
- 送出前記錄使用者或專案、client request ID、模型與設定;收到後再保存 TokAtlas task ID。
- 圖片轉影片請先核對模型的檔案格式、像素、比例及安全規則;某模型可接受的圖片不代表另一模型也可接受。
步驟 1:提交文字轉影片任務
curl --fail-with-body --silent --show-error \ --request POST "https://api.tokatlas.com/v1/videos" \ --header "Authorization: Bearer $TOKATLAS_API_KEY" \ --form "model=$VIDEO_MODEL_ID" \ --form "prompt=A ceramic cup on a table, steam rising, slow camera movement" \ --form "seconds=4" \ --form "size=720x1280"
立即保存回應中的 id。本教學整理期間的一次帳戶層級直接請求,向 POST /v1/videos 送出 dreamina-seedance-2-5-intl-260801 後回傳 queued。這僅證明當時該帳戶的任務已被接受;不代表影片已完成、品質保證、所有帳戶都有模型權限或最終費用已結算。
可控 prompt 的寫法
把 prompt 寫成「主體 + 動作 + 場景/時間 + 鏡頭運動 + 光線/風格 + 限制」。先用短片測試,每次只改一個變因,才能回查不理想結果的原因。
步驟 2:安全輪詢影片任務
for attempt in range(120):
task = requests.get(
f"https://api.tokatlas.com/v1/videos/{task_id}", headers=headers
).json()
status = task.get("status")
if status == "completed":
break
if status == "failed":
raise RuntimeError(task.get("error") or task)
if status not in {"queued", "in_progress"}:
raise RuntimeError(task)
time.sleep(5)
讓背景工作者輪詢,讓原始請求回傳 task ID。網路逾時時,不要立即重送:先以保存的 task ID 或 request record 查詢原任務。設定輪詢間隔、最大等待時間與有界退避,服務重啟後從同一 ID 繼續,而不是建立重複影片。
步驟 3:只在完成後下載
curl --fail-with-body --silent --show-error \ --request GET "https://api.tokatlas.com/v1/videos/$TASK_ID/content" \ --header "Authorization: Bearer $TOKATLAS_API_KEY" \ --output video.mp4
同時保存檔案位置、task ID、輸入設定和完成時間。這樣可重試下載而不必重新生成,也能為使用者提供可靠的作品紀錄。
Seedance API 整合注意事項
若帳戶內已啟用精確的 Seedance 模型 ID,仍應採用相同的「提交 → 輪詢 → 下載」生命週期,而不是假設為即時影片 API。模型可用性與接受的欄位可能調整;每次產品上線前都應重新檢查模型目錄與小額測試結果。
常見錯誤與正確處理
- 401 / 403:先檢查 API Key、Authorization header、帳戶與模型權限;不要將金鑰放在瀏覽器。
- 400:核對必填欄位和模型是否支援秒數、size 或參考圖片;不要假設模型可交換參數。
- 429:採用有界退避並觀察帳戶限制;不要緊密重試。
- queued / in_progress:繼續查同一 task ID;不要下載或重複建立任務。
- failed:保留 task ID、輸入 metadata 和錯誤;不要寫成影片已完成。
官方文件與下一步
請先閱讀 TokAtlas 影片生成總覽、從圖片生成影片指南、影片 Tool Calling 指南 與 API 基礎說明。建立 API Key、選擇帳戶已啟用的影片模型,先完成提交 → 輪詢 → 下載的閉環,再逐步加入模型專屬能力。