ADD_KEYFRAMES API 接口文档
接口信息
POST /openapi/capcut-tools/v1/add_keyframes
功能描述
向现有草稿中添加关键帧。该接口用于在指定的片段上添加关键帧动画，支持多种属性类型的关键帧设置，如位置、缩放、旋转、透明度等。关键帧可以用于创建复杂的动画效果，增强视频的视觉表现力。
更多文档
📖 更多详细文档和教程请访问：https://docs.agent-ai-tools.com
请求参数
{
"draft_url": "https://agent.aigc-ai.com/openapi/capcut-tools/v1/get_draft?draft_id=2025092811473036584258",
"keyframes": "[{\"segment_id\":\"d62994b4-25fe-422a-a123-87ef05038558\",\"property\":\"KFTypePositionX\",\"offset\":0.5,\"value\":-0.1}]"
}
参数说明
| 参数名 |
类型 |
必填 |
默认值 |
说明 |
| draft_url |
string |
✅ |
- |
目标草稿的完整 URL |
| keyframes |
string |
✅ |
- |
关键帧信息列表的 JSON 字符串 |
keyframes 参数详解
基本结构
keyframes 是一个 JSON 字符串，包含关键帧数组，每个关键帧对象包含以下字段：
| 字段名 |
类型 |
必填 |
说明 |
| segment_id |
string |
✅ |
目标片段的唯一标识 ID |
| property |
string |
✅ |
动画属性类型，支持的类型见下表 |
| offset |
number |
✅ |
关键帧在片段中的时间偏移（0-1 范围，0 表示开始，1 表示结束） |
| value |
number |
✅ |
属性在该时间点的值 |
支持的动画属性类型
| 属性类型 |
描述 |
值范围 |
示例 |
| KFTypePositionX |
X 轴位置 |
-1.0 到 1.0 |
0.0 (居中), -0.5 (左移), 0.5 (右移) |
| KFTypePositionY |
Y 轴位置 |
-1.0 到 1.0 |
0.0 (居中), -0.5 (上移), 0.5 (下移) |
| KFTypeScaleX |
X 轴缩放 |
0.1 到 10.0 |
1.0 (原始), 0.5 (缩小), 2.0 (放大) |
| KFTypeScaleY |
Y 轴缩放 |
0.1 到 10.0 |
1.0 (原始), 0.5 (缩小), 2.0 (放大) |
| KFTypeRotation |
旋转角度 |
-360 到 360 |
0 (无旋转), 90 (顺时针 90 度) |
| KFTypeAlpha |
透明度 |
0.0 到 1.0 |
1.0 (不透明), 0.5 (半透明), 0.0 (透明) |
响应格式
成功响应 (200)
{
"draft_url": "https://agent.aigc-ai.com/openapi/capcut-tools/v1/get_draft?draft_id=2025092811473036584258",
"keyframes_added": 3,
"affected_segments": ["segment_001", "segment_002"]
}
响应字段说明
| 字段名 |
类型 |
说明 |
| draft_url |
string |
更新后的草稿 URL |
| keyframes_added |
integer |
添加的关键帧数量 |
| affected_segments |
array |
受影响的片段 ID 列表 |
错误响应 (4xx/5xx)
{
"detail": "错误信息描述"
}
使用示例
cURL 示例
1. 基本关键帧添加
curl -X POST https://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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}]"
}'
错误码说明
| 错误码 |
错误信息 |
说明 |
解决方案 |
| 400 |
draft_url 是必填项 |
缺少草稿 URL 参数 |
提供有效的 draft_url |
| 400 |
keyframes 是必填项 |
缺少关键帧参数 |
提供有效的 keyframes 数据 |
| 400 |
无效的关键帧信息，请检查 keyframes 字段值是否正确 |
关键帧数据格式错误 |
检查关键帧数据格式是否符合要求 |
| 404 |
草稿不存在 |
指定的草稿 URL 无效 |
检查草稿 URL 是否正确 |
| 404 |
片段未找到 |
指定的 segment_id 在草稿中不存在 |
确认片段 ID 是否正确 |
| 400 |
无效的片段类型 |
该片段不支持关键帧功能 |
确保为目标片段是视觉片段（视频、图片、贴纸、文本） |
| 400 |
无效的关键帧属性类型 |
指定的 property 类型不受支持 |
检查属性类型是否在支持列表中 |
| 500 |
关键帧添加失败 |
内部处理错误 |
联系技术支持 |
注意事项
- 片段 ID 验证: segment_id 必须是草稿中存在的有效片段 ID
- 片段类型限制: 只有视觉片段（视频、图片、贴纸、文本）支持关键帧
- 时间偏移范围: offset 值必须在 0.0-1.0 范围内
- 属性值范围: 不同的属性类型有不同的值范围限制
- 重复关键帧: 相同片段相同属性的关键帧会被累加，不会覆盖
- 性能考虑: 单次请求建议不超过 100 个关键帧
- 缩放属性: 设置 KFTypeScaleX 或 KFTypeScaleY 会自动取消锁定 XY 轴缩放比例
工作流程
- 验证必填参数（draft_url, keyframes）
- 解析关键帧数据 JSON 字符串
- 从缓存中获取草稿
- 验证每个关键帧数据的有效性
- 查找目标片段并验证片段类型
- 为每个关键帧创建关键帧列表并添加到片段
- 保存草稿
- 返回添加结果信息
相关接口