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 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 #

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 #

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

Language Switch #

中文版 | English