视频生成接口

目录

1. 简介
2. 核心API接口
3. 请求参数说明
4. 响应格式
5. 错误码说明
6. 使用示例
7. 注意事项
8. 相关接口

简介

视频生成接口是 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地址
  • 格式：https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id={草稿ID}
  • 示例："https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
  • 获取方式：通过创建草稿或保存草稿接口获取

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

注意事项

1. 处理时间: 视频生成是耗时操作，可能需要几分钟到几十分钟
2. 文件大小: 草稿复杂度和素材数量会影响处理时间
3. 网络稳定: 确保素材URL可以稳定访问
4. 超时设置: 建议设置较长的超时时间或使用轮询机制
5. 并发限制: 避免同时生成大量视频
6. 存储空间: 生成的视频文件可能很大，注意存储空间
7. URL有效期: 生成的video_url可能有时效性限制
8. 系统要求: 视频生成功能仅在Windows系统上可用

相关接口

• 创建草稿
• 保存草稿
• 添加视频
• 添加音频
• 添加图片
• 获取草稿

附录

• 接口文档： docs.jcaigc.cn
• 效果案例： www.jcaigc.cn/workflow
• 开源仓库： capcut-mate