# GEN_VIDEO_STATUS API 接口文档

## 接口信息

```bash
POST /openapi/capcut-mate/v1/gen_video_status
```

## 功能描述

查询视频生成任务的状态和进度。配合 [gen_video](./gen_video.md) 接口使用，用于实时跟踪视频生成任务的执行情况，包括任务状态、进度百分比、完成结果等信息。

## 更多文档

📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)

## 请求参数

```json
{
  "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](./gen_video.md) 接口提交任务后返回的draft_url

## 响应格式

### 成功响应 (200)

#### 任务等待中

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

#### 任务处理中

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

#### 任务已完成

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

#### 任务失败

```json
{
  "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 - 任务不存在

```json
{
  "detail": "视频生成任务未找到"
}
```

#### 500 Internal Server Error - 查询失败

```json
{
  "detail": "视频任务状态查询失败"
}
```

## 使用示例

### cURL 示例

#### 1. 查询任务状态

```bash
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](./gen_video.md) - 提交视频生成任务
- [create_draft](./create_draft.md) - 创建新的草稿文件
- [save_draft](./save_draft.md) - 保存草稿文件

---

<div align="right">

📚 **项目资源**  
GitHub搜索capcut-mate就能找到。

</div>

查询视频生成任务的状态和进度。配合 gen_video 接口使用，用于实时跟踪视频生成任务的执行情况，包括任务状态、进度百分比、完成结果等信息。

【剪映小助手】查询视频生成任务的状态和进度

音视频

开发工具

GitHub

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【剪映小助手】查询视频生成任务的状态和进度-腾讯云开发者社区-腾讯云

【剪映小助手】查询视频生成任务的状态和进度

【剪映小助手】查询视频生成任务的状态和进度

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐