KEYFRAMES_INFOS API 接口文档

🌐 语言切换

中文版 | English

接口信息

POST /openapi/capcut-mate/v1/keyframes_infos

功能描述

根据关键帧类型、位置比例和值生成关键帧信息。该接口将关键帧配置转换为剪映草稿所需的关键帧信息格式。

请求参数

{
  "ctype": "KFTypePositionX",
  "offsets": "0|50|100",
  "values": "0|960|1920",
  "segment_infos": [
    {"id": "segment1", "start": 0, "end": 5000000}
  ],
  "height": 1080,
  "width": 1920
}

参数说明

参数名	类型	必填	默认值	说明
ctype	string	✅	-	关键帧类型：KFTypePositionX（X轴移动，需要 width）、KFTypePositionY（Y轴移动，需要 height）、KFTypeRotation（0-360）、UNIFORM_SCALE（0.01-5）、KFTypeAlpha（0-1）
offsets	string	✅	-	位置比例，用 | 分隔，如 "0|100"（开头和结尾）、"0|50|100"（开头、中间、结尾）
values	string	✅	-	对应 offsets 的值，用 | 分隔，元素个数须与 offsets 一致，如 "1|2"、"1|2|1"
segment_infos	array[object]	✅	-	轨道数据（片段对象数组），每项含 id、start、end（微秒）
height	integer	❌	None	高度，用于 KFTypePositionY 值的归一化
width	integer	❌	None	宽，用于 KFTypePositionX 值的归一化

##响应格式

成功响应 (200)

{
  "code": 0,
  "message": "success",
  "keyframes_infos": "[{\"offset\":0,\"property\":\"KFTypePositionX\",\"segment_id\":\"segment1\",\"value\":0.0},{\"offset\":2500000,\"property\":\"KFTypePositionX\",\"segment_id\":\"segment1\",\"value\":0.5},{\"offset\":5000000,\"property\":\"KFTypePositionX\",\"segment_id\":\"segment1\",\"value\":1.0}]"
}

###响应字段说明

字段名	类型	说明
keyframes_infos	string	关键帧信息JSON字符串

错误响应

{
  "code": 1001,
  "message": "参数校验失败"
}

使用示例

cURL 示例

1.基本关键帧信息生成

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/keyframes_infos \
  -H "Content-Type: application/json" \
  -d '{
    "ctype": "UNIFORM_SCALE",
    "offsets": "0|100",
    "values": "0.5|1.5",
    "segment_infos": [{"id": "segment1", "start": 0, "end": 5000000}]
  }'

2.位置关键帧信息

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/keyframes_infos \
  -H "Content-Type: application/json" \
  -d '{
    "ctype": "KFTypePositionX",
    "offsets": "0|30|70|100",
    "values": "0|384|1536|1920",
    "segment_infos": [{"id": "segment1", "start": 0, "end": 10000000}],
    "height": 1080,
    "width": 1920
  }'

##错误码说明

错误码	错误信息	说明	解决方案
1001	参数校验失败	请求体未通过字段校验（缺少 ctype/offsets/values/segment_infos，或 offsets/values 不是字符串）	检查参数类型与必填字段
9998	系统内部错误	offsets 与 values 用 | 分隔的元素个数不一致	保证 offsets 与 values 的元素个数一致

注意事项

1. 元素数量匹配: offsets和values用 | 分隔的元素个数必须相同
2. 时间单位:所有时间参数使用微秒（1秒 = 1,000,000微秒）
3. 关键帧类型:支持 KFTypePositionX、KFTypePositionY、KFTypeRotation、UNIFORM_SCALE、KFTypeAlpha
4. 位置比例: offsets值为 0-100 的百分比，关键帧的 offset 相对片段起点计算
5. 分辨率设置: KFTypePositionX/KFTypePositionY 的值会除以 width/height 进行归一化

##工作流程

1.验证必填参数（ctype, offsets, values, segment_infos） 2. 检查 offsets 与 values 的元素个数是否一致 3.验证参数有效性 4. 为每个offset生成对应的关键帧信息 5.应用分辨率参数 6.将信息转换为JSON字符串格式 7. 返回处理结果

##相关接口

• 创建草稿
• 添加关键帧
• 保存草稿

---

📚 项目资源
GitHub: https://github.com/Hommy-master/capcut-mate
Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

语言切换

中文版 | English