---
url: /docs/gen_video_status.md
description: 'Poll video export status: pending, processing, completed, or failed.'
---

# GEN\_VIDEO\_STATUS API Documentation

## 🌐 Language Switch

[中文版](/docs/gen_video_status.zh) | [English](/docs/gen_video_status)

## Interface Information

```bash
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](/docs/gen_video) interface to track the execution of video generation tasks in real-time, including task status, progress percentage, completion results, and other information.

Poll every 3-5 seconds. Read video\_url only when completed; read error\_message when failed. Do not stop while pending or processing.

## Request Parameters

```json
{
  "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](/docs/gen_video) interface

## Response Format

### Success Response (200)

#### Task Waiting

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

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

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

```json
{
  "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 | Task start time (ISO format) |
| completed\_at | string|null | Task completion time (ISO format) |

### Error Response

#### 2031 Video Generation Task Not Found

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

#### 2032 Video Task Status Query Failed

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

## Usage Examples

### cURL Examples

#### 1. Query Task Status

```bash
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](/docs/gen_video) - Submit video generation task
* [create\_draft](/docs/create_draft) - Create new draft file
* [save\_draft](/docs/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

[中文版](/docs/gen_video_status.zh) | [English](/docs/gen_video_status)