GEN_VIDEO_STATUS API Documentation

🌐 Language Switch

中文版 | English

Interface Information

POST /openapi/capcut-mate/v1/gen_video_status

Function Description

Query the status and progress of video generation tasks. Used together with the gen_video interface to track the execution of video generation tasks in real-time, including task status, progress percentage, completion results, and other information.

Request Parameters

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

Parameter Description

Parameter	Type	Required	Default	Description
draft_url	string	✅	-	Draft URL, same as the URL used when submitting the task

Parameter Details

Draft URL Parameter

• draft_url: Complete URL of the draft, used to identify the video generation task to query status for
  • Format: Must be a valid URL format
  • Example: "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
  • Acquisition Method: draft_url returned after submitting task via gen_video interface

Response Format

Success Response (200)

Task Waiting

{
  "code": 0,
  "message": "success",
  "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
}

Task Processing

{
  "code": 0,
  "message": "success",
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258", 
  "status": "processing",
  "progress": 70,
  "video_url": "",
  "error_message": "",
  "created_at": "2024-09-24T10:30:00.000Z",
  "started_at": "2024-09-24T10:30:05.000Z",
  "completed_at": null
}

Task Completed

{
  "code": 0,
  "message": "success",
  "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"
}

Task Failed

{
  "code": 0,
  "message": "success",
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "status": "failed",
  "progress": 0,
  "video_url": "",
  "error_message": "Export draft failed",
  "created_at": "2024-09-24T10:30:00.000Z",
  "started_at": "2024-09-24T10:30:05.000Z",
  "completed_at": "2024-09-24T10:32:15.000Z"
}

Response Field Description

Field	Type	Description
draft_url	string	Draft URL
status	string	Task status: pending/processing/completed/failed
progress	integer	Task progress (0-100)
video_url	string	Generated video URL (only has value in completed status)
error_message	string	Error message (only has value in failed status)
created_at	string	Task creation time (ISO format)
started_at	string	null
completed_at	string	null

Error Response

2031 Video Generation Task Not Found

{
  "code": 2031,
  "message": "Video generation task not found"
}

2032 Video Task Status Query Failed

{
  "code": 2032,
  "message": "Video task status query failed"
}

Usage Examples

cURL Examples

1. Query Task Status

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/gen_video_status \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
  }'

Error Code Description

Error Code	Error Message	Description	Solution
1001	Parameter validation failed	draft_url is missing or not a string	Provide a valid draft_url
2031	Video generation task not found	The draft URL has no corresponding video generation task	Confirm if task has been submitted via gen_video interface
2032	Video task status query failed	Internal processing error	Retry later or contact technical support

Notes

1. Polling Interval: Suggest querying task status every 5-10 seconds
2. Timeout Settings: Suggest setting total timeout time (e.g. 10 minutes)
3. Status Handling: Provide different user feedback based on different statuses
4. Error Handling: Properly handle task failure situations
5. Progress Display: Utilize progress field to display progress bar
6. Task Uniqueness: Same draft URL can only have one ongoing task

Workflow

1. Validate required parameters (draft_url)
2. Query task status from task manager
3. Convert internal status to API response format
4. Return task status information

Related Interfaces

• gen_video - Submit video generation task
• create_draft - Create new draft file
• save_draft - Save draft file

---

📚 Project Resources
GitHub: https://github.com/Hommy-master/capcut-mate
Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

Language Switch

中文版 | English