GEN_VIDEO_STATUS API 接口文檔

接口信息

POST /openapi/capcut-mate/v1/gen_video_status

功能描述

查詢視頻生成任務的狀態和進度。配合 gen_video 接口使用，用於實時跟蹤視頻生成任務的執行情況，包括任務狀態、進度百分比、完成結果等信息。

更多文檔

📖 更多詳細文檔和教程請訪問：https://docs.jcaigc.cn

請求參數

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}

參數説明

參數名 類型 必填 默認值 説明
draft_url string ✅ - 草稿URL，與提交任務時使用的URL相同

參數詳解

草稿URL參數
  • draft_url: 草稿的完整URL，用於標識要查詢狀態的視頻生成任務
    • 格式：必須是有效的URL格式
    • 示例："https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
    • 獲取方式：通過 gen_video 接口提交任務後返回的draft_url

響應格式

成功響應 (200)

任務等待中
{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "status": "pending",
  "progress": 0,
  "video_url": "",
  "error_message": "",
  "created_at": "2024-09-24T10:30:00.000Z",
  "started_at": null,
  "completed_at": null
}
任務處理中
{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258", 
  "status": "processing",
  "progress": 65,
  "video_url": "",
  "error_message": "",
  "created_at": "2024-09-24T10:30:00.000Z",
  "started_at": "2024-09-24T10:30:05.000Z",
  "completed_at": null
}
任務已完成
{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "status": "completed",
  "progress": 100,
  "video_url": "https://video-output.assets.jcaigc.cn/generated/video_abc123def456ghi789.mp4",
  "error_message": "",
  "created_at": "2024-09-24T10:30:00.000Z",
  "started_at": "2024-09-24T10:30:05.000Z",
  "completed_at": "2024-09-24T10:35:30.000Z"
}
任務失敗
{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "status": "failed",
  "progress": 0,
  "video_url": "",
  "error_message": "導出草稿失敗: 剪映導出結束但目標文件未生成，請檢查磁盤空間或剪映版本",
  "created_at": "2024-09-24T10:30:00.000Z",
  "started_at": "2024-09-24T10:30:05.000Z",
  "completed_at": "2024-09-24T10:32:15.000Z"
}

響應字段説明

字段名 類型 説明
draft_url string 草稿URL
status string 任務狀態：pending/processing/completed/failed
progress integer 任務進度（0-100）
video_url string 生成的視頻URL（僅在completed狀態時有值）
error_message string 錯誤信息（僅在failed狀態時有值）
created_at string 任務創建時間（ISO格式）
started_at string|null 任務開始時間（ISO格式）
completed_at string|null 任務完成時間（ISO格式）

錯誤響應 (4xx/5xx)

404 Not Found - 任務不存在
{
  "detail": "視頻生成任務未找到"
}
500 Internal Server Error - 查詢失敗
{
  "detail": "視頻任務狀態查詢失敗"
}

使用示例

cURL 示例

1. 查詢任務狀態
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/gen_video_status \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL"
  }'

錯誤碼説明

錯誤碼 錯誤信息 説明 解決方案
400 draft_url是必填項 缺少草稿URL參數 提供有效的draft_url
400 無效的草稿URL draft_url格式不正確 檢查草稿URL格式是否正確
404 視頻生成任務未找到 指定的草稿URL沒有對應的視頻生成任務 確認是否已通過gen_video接口提交任務
500 視頻任務狀態查詢失敗 內部處理錯誤 稍後重試或聯繫技術支持

注意事項

  1. 輪詢間隔: 建議每5-10秒查詢一次任務狀態
  2. 超時設置: 建議設置總超時時間（如10分鐘）
  3. 狀態處理: 根據不同狀態提供不同的用户反饋
  4. 錯誤處理: 妥善處理任務失敗情況
  5. 進度顯示: 利用progress字段顯示進度條
  6. 任務唯一性: 同一草稿URL只能有一個進行中的任務

工作流程

  1. 驗證必填參數（draft_url）
  2. 從任務管理器中查詢任務狀態
  3. 將內部狀態轉換為API響應格式
  4. 返回任務狀態信息

相關接口

  • gen_video - 提交視頻生成任務
  • create_draft - 創建新的草稿文件
  • save_draft - 保存草稿文件

📚 項目資源
GitHub: 搜索capcut-mate即可找到。