add_keyframes 接口文档 #

接口描述 #

向剪映草稿添加关键帧，支持多种动画属性的关键帧设置。

更多文档 #

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

相关接口 #

• create_draft - 创建新的剪映草稿
• add_videos - 向草稿添加视频内容
• save_draft - 保存草稿更改

接口信息 #

• 方法: POST
• 路径: /openapi/capcut-mate/v1/add_keyframes
• Content-Type: application/json

请求参数 #

请求体 #

{
  "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字符串，包含关键帧数组，每个关键帧对象包含以下字段：

支持的动画属性类型 #

响应结果 #

成功响应 #

{
  "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"]
}

响应字段说明 #

错误响应 #

{
  "code": 2013,
  "message": "无效的关键帧信息，请检查keyframes字段值是否正确"
}

使用示例 #

cURL 示例 #

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

Python 示例 #

import requests
import json

url = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_keyframes"
keyframes_data = [
    {
        "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
    }
]

payload = {
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "keyframes": json.dumps(keyframes_data)
}

response = requests.post(url, json=payload)
print(response.json())

注意事项 #

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

错误码说明 #

相关接口 #

• create_draft - 创建新的剪映草稿
• add_videos - 向草稿添加视频内容
• save_draft - 保存草稿更改
• get_draft - 获取草稿详情

技术实现 #

文件结构 #

• src/service/add_keyframes.py - 关键帧添加服务
• src/schemas/add_keyframes.py - 请求响应数据模型
• src/pyJianYingDraft/keyframe.py - 关键帧核心实现

核心逻辑 #

1. 参数验证: 验证草稿URL、关键帧数据格式和属性类型
2. 片段检查: 确认目标片段存在且支持关键帧功能
3. 关键帧添加: 将关键帧数据写入草稿文件
4. 结果返回: 返回添加的关键帧数量和受影响的片段