ADD_KEYFRAMES API 接口文档

接口信息

POST /openapi/capcut-mate/v1/add_keyframes

功能描述

向现有草稿中添加关键帧。该接口用于在指定的片段上添加关键帧动画，支持多种属性类型的关键帧设置，如位置、缩放、旋转、透明度等。关键帧可以用于创建复杂的动画效果，增强视频的视觉表现力。

更多文档

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

请求参数

{
   
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "keyframes": "[{\"segment_id\":\"d62994b4-25fe-422a-a123-87ef05038558\",\"property\":\"KFTypePositionX\",\"offset\":0.5,\"value\":-0.1}]"
}

参数说明

keyframes 参数详解

基本结构

keyframes 是一个JSON字符串，包含关键帧数组，每个关键帧对象包含以下字段：

支持的动画属性类型

响应格式

成功响应 (200)

{
   
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "keyframes_added": 3,
  "affected_segments": ["segment_001", "segment_002"]
}

响应字段说明

错误响应 (4xx/5xx)

{
   
  "detail": "错误信息描述"
}

使用示例

cURL 示例

1. 基本关键帧添加

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_keyframes \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "keyframes": "[{\"segment_id\":\"d62994b4-25fe-422a-a123-87ef05038558\",\"property\":\"KFTypePositionX\",\"offset\":0,\"value\":0},{\"segment_id\":\"d62994b4-25fe-422a-a123-87ef05038558\",\"property\":\"KFTypePositionX\",\"offset\":1,\"value\":-0.5}]"
  }'

2. 多属性关键帧

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_keyframes \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "keyframes": "[{\"segment_id\":\"segment-uuid\",\"property\":\"KFTypePositionX\",\"offset\":0,\"value\":0},{\"segment_id\":\"segment-uuid\",\"property\":\"KFTypePositionY\",\"offset\":0,\"value\":0},{\"segment_id\":\"segment-uuid\",\"property\":\"KFTypeRotation\",\"offset\":0.5,\"value\":90},{\"segment_id\":\"segment-uuid\",\"property\":\"KFTypeAlpha\",\"offset\":1,\"value\":0}]"
  }'

错误码说明

注意事项

1. 片段ID验证: segment_id 必须是草稿中存在的有效片段ID
2. 片段类型限制: 只有视觉片段（视频、图片、贴纸、文本）支持关键帧
3. 时间偏移范围: offset 值必须在 0.0-1.0 范围内
4. 属性值范围: 不同的属性类型有不同的值范围限制
5. 重复关键帧: 相同片段相同属性的关键帧会被累加，不会覆盖
6. 性能考虑: 单次请求建议不超过100个关键帧
7. 缩放属性: 设置KFTypeScaleX或KFTypeScaleY会自动取消锁定XY轴缩放比例

工作流程

1. 验证必填参数（draft_url, keyframes）
2. 解析关键帧数据JSON字符串
3. 从缓存中获取草稿
4. 验证每个关键帧数据的有效性
5. 查找目标片段并验证片段类型
6. 为每个关键帧创建关键帧列表并添加到片段
7. 保存草稿
8. 返回添加结果信息

相关接口

• 创建草稿
• 添加视频
• 添加音频
• 添加图片
• 保存草稿
• 生成视频