视频生成接口
目录
简介
视频生成接口是 Capcut Mate 项目的核心功能模块，提供完整的云端视频渲染服务。该接口支持异步视频生成、实时状态查询和结果获取，适用于各种视频创作场景。
文档已简化为核心API文档，专注于gen_video和gen_video_status两个核心接口的使用说明。
主要特性包括：
- 异步视频生成任务处理
- 实时进度监控和状态查询
- 多种输出格式支持
- 完善的错误处理和恢复机制
- 可选的API密钥验证和积分系统
- 国际化双语API文档支持
核心API接口
视频生成接口 (/v1/gen_video)
提交视频生成任务。该接口采用异步处理模式，立即返回任务提交状态，视频生成在后台进行。支持任务排队，确保系统稳定性。
接口信息
POST /openapi/capcut-mate/v1/gen_video
状态查询接口 (/v1/gen_video_status)
查询视频生成任务状态。与gen_video接口配合使用，实时跟踪视频生成任务的执行状态，包括任务状态、进度百分比、完成结果等信息。
接口信息
POST /openapi/capcut-mate/v1/gen_video_status
请求参数说明
gen_video 接口参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
| apiKey | string | ❌ | - | API密钥（可选，用于积分验证） |
gen_video_status 接口参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| draft_url | string | ✅ | - | 草稿URL，与提交任务时使用的URL相同 |
参数详解
草稿URL参数
- draft_url: 草稿的完整URL地址
API密钥参数
- apiKey: 可选的API密钥，必须是合法的UUID格式
- 用途：用于积分验证和计费
- 格式：标准UUID格式字符串
响应格式
gen_video 接口响应
成功响应 (200)
{
"message": "视频生成任务已提交，请使用draft_url查询进度"
}
响应字段说明
| 字段名 | 类型 | 说明 |
|---|---|---|
| message | string | 响应消息 |
gen_video_status 接口响应
成功响应 (200)
任务等待中
{
"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
}
任务处理中
{
"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
}
任务已完成
{
"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"
}
任务失败
{
"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"
}
响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| 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格式） |
错误码说明
gen_video 接口错误码
| 错误码 | 错误信息 | 说明 | 解决方案 |
|---|---|---|---|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | draft_url格式无效 | URL格式不正确 | 检查URL格式是否正确 |
| 404 | 草稿不存在 | 指定的草稿无法找到 | 确认草稿URL是否正确且存在 |
| 400 | 草稿内容为空 | 草稿中没有可导出的内容 | 确保草稿包含视频、音频或图片素材 |
| 400 | 素材无法访问 | 草稿中的素材文件无法下载 | 检查素材URL是否有效 |
| 500 | 视频渲染失败 | 视频处理过程中出错 | 检查草稿内容或联系技术支持 |
| 500 | 音频处理失败 | 音频混合过程中出错 | 检查音频格式或联系技术支持 |
| 500 | 编码失败 | 最终视频编码失败 | 联系技术支持 |
| 503 | 服务繁忙 | 渲染服务器负载过高 | 稍后重试 |
| 504 | 处理超时 | 视频生成超时 | 简化草稿内容或稍后重试 |
| 500 | 视频生成任务提交失败 | 内部处理错误 | 联系技术支持 |
gen_video_status 接口错误码
| 错误码 | 错误信息 | 说明 | 解决方案 |
|---|---|---|---|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | Invalid draft_url | draft_url格式不正确 | 检查是否draft URL格式正确 |
| 404 | 视频生成任务未找到 | 指定的草稿URL没有对应的视频生成任务 | 确认是否已通过gen_video接口提交任务 |
| 500 | 视频任务状态查询失败 | 内部处理错误 | 稍后重试或联系技术支持 |
使用示例
cURL 示例
1. 基本视频生成
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/gen_video \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL"
}'
2. 带API密钥的视频生成
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/gen_video \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"apiKey": "YOUR_API_KEY"
}'
3. 查询任务状态
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"
}'
注意事项
- 处理时间: 视频生成是耗时操作，可能需要几分钟到几十分钟
- 文件大小: 草稿复杂度和素材数量会影响处理时间
- 网络稳定: 确保素材URL可以稳定访问
- 超时设置: 建议设置较长的超时时间或使用轮询机制
- 并发限制: 避免同时生成大量视频
- 存储空间: 生成的视频文件可能很大，注意存储空间
- URL有效期: 生成的video_url可能有时效性限制
- 系统要求: 视频生成功能仅在Windows系统上可用
