【开源剪映小助手】视频生成接口

用户59913033478
4 阅读6分钟

视频生成接口

目录

  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_urlstring✅-目标草稿的完整URL
apiKeystring❌-API密钥（可选，用于积分验证）

gen_video_status 接口参数

参数名类型必填默认值说明
draft_urlstring✅-草稿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查询进度"
}
响应字段说明
字段名类型说明
messagestring响应消息

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_urlstring草稿URL
statusstring任务状态：pending/processing/completed/failed
progressinteger任务进度（0-100）
video_urlstring生成的视频URL（仅在completed状态时有值）
error_messagestring错误信息（仅在failed状态时有值）
created_atstring任务创建时间（ISO格式）
started_atstring/null任务开始时间（ISO格式）
completed_atstring/null任务完成时间（ISO格式）

错误码说明

gen_video 接口错误码

错误码错误信息说明解决方案
400draft_url是必填项缺少草稿URL参数提供有效的draft_url
400draft_url格式无效URL格式不正确检查URL格式是否正确
404草稿不存在指定的草稿无法找到确认草稿URL是否正确且存在
400草稿内容为空草稿中没有可导出的内容确保草稿包含视频、音频或图片素材
400素材无法访问草稿中的素材文件无法下载检查素材URL是否有效
500视频渲染失败视频处理过程中出错检查草稿内容或联系技术支持
500音频处理失败音频混合过程中出错检查音频格式或联系技术支持
500编码失败最终视频编码失败联系技术支持
503服务繁忙渲染服务器负载过高稍后重试
504处理超时视频生成超时简化草稿内容或稍后重试
500视频生成任务提交失败内部处理错误联系技术支持

gen_video_status 接口错误码

错误码错误信息说明解决方案
400draft_url是必填项缺少草稿URL参数提供有效的draft_url
400Invalid draft_urldraft_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系统上可用

相关接口

avatar
文章
阅读
粉丝