# ADD_KEYFRAMES API 接口文档

## 接口信息

``` 
POST /openapi/capcut-mate/v1/add_keyframes
```

## 功能描述

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

## 更多文档

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

## 请求参数

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

### 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| 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)

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

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 更新后的草稿URL |
| keyframes_added | integer | 添加的关键帧数量 |
| affected_segments | array | 受影响的片段ID列表 |

### 错误响应 (4xx/5xx)

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

## 使用示例

### cURL 示例

#### 1. 基本关键帧添加

```bash
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. 多属性关键帧

```bash
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}]"
  }'
```

## 错误码说明

| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | keyframes是必填项 | 缺少关键帧参数 | 提供有效的keyframes数据 |
| 400 | 无效的关键帧信息，请检查keyframes字段值是否正确 | 关键帧数据格式错误 | 检查关键帧数据格式是否符合要求 |
| 404 | 草稿不存在 | 指定的草稿URL无效 | 检查草稿URL是否正确 |
| 404 | 片段未找到 | 指定的segment_id在草稿中不存在 | 确认片段ID是否正确 |
| 400 | 无效的片段类型 | 该片段不支持关键帧功能 | 确保为目标片段是视觉片段（视频、图片、贴纸、文本） |
| 400 | 无效的关键帧属性类型 | 指定的property类型不受支持 | 检查属性类型是否在支持列表中 |
| 500 | 关键帧添加失败 | 内部处理错误 | 联系技术支持 |

## 注意事项

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. 返回添加结果信息

## 相关接口

- [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)

---

<div align="right">

📚 **项目资源**  
GitHub搜索capcut-mate就能找到。

</div>

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

【剪映小助手】向现有草稿中添加关键帧

音视频

开发工具

GitHub

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【剪映小助手】向现有草稿中添加关键帧-腾讯云开发者社区-腾讯云

【剪映小助手】向现有草稿中添加关键帧

【剪映小助手】向现有草稿中添加关键帧

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐