capcut-mate/docs/gen_video_status.md

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.

More Documentation

📖 For more detailed documentation and tutorials, please visit: https://docs.jcaigc.cn

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

{
  "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

{
  "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
}

Task Completed

{
  "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

{
  "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: Jianying export ended but target file was not generated, please check disk space or Jianying version",
  "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 (4xx/5xx)

404 Not Found - Task Does Not Exist

{
  "detail": "Video generation task not found"
}

500 Internal Server Error - Query Failed

{
  "detail": "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": "YOUR_DRAFT_URL"
  }'

Error Code Description

Error Code	Error Message	Description	Solution
400	draft_url is required	Missing draft URL parameter	Provide a valid draft_url
400	Invalid draft URL	draft_url format is incorrect	Check if draft URL format is correct
404	Video generation task not found	Specified draft URL has no corresponding video generation task	Confirm if task has been submitted via gen_video interface
500	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