opensource/capcut-mate
3
0
Fork 0
mirror of https://github.com/Hommy-master/capcut-mate.git synced 2026-09-01 15:32:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

优化文档。

Browse Source
This commit is contained in:
Hommy
2025-12-01 22:58:27 +08:00
parent 9307bb6402
commit 7d9a7d288a
1 changed files with 73 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/add_keyframes.md
+73 -90
View File
@@ -1,26 +1,21 @@
# add_keyframes 接口文档
# ADD_KEYFRAMES API 接口文档
## 接口描述
向剪映草稿添加关键帧，支持多种动画属性的关键帧设置。
## 接口信息
```
POST /openapi/capcut-mate/v1/add_keyframes
```
## 功能描述
向现有草稿中添加关键帧。该接口用于在指定的片段上添加关键帧动画，支持多种属性类型的关键帧设置，如位置、缩放、旋转、透明度等。关键帧可以用于创建复杂的动画效果，增强视频的视觉表现力。
## 更多文档
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 相关接口
- [create_draft](./create_draft.md) - 创建新的剪映草稿
- [add_videos](./add_videos.md) - 向草稿添加视频内容
- [save_draft](./save_draft.md) - 保存草稿更改
## 接口信息
- **方法**: POST
- **路径**: `/openapi/capcut-mate/v1/add_keyframes`
- **Content-Type**: `application/json`
## 请求参数
### 请求体
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
@@ -30,22 +25,24 @@
### 参数说明
| 字段名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| draft_url | string | 是 | 草稿URL |
| keyframes | string | 是 | 关键帧信息列表的JSON字符串 |
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
| keyframes | string | ✅ | - | 关键帧信息列表的JSON字符串 |
### keyframes 字段详细说明
### keyframes 参数详解
#### 基本结构
keyframes 是一个JSON字符串，包含关键帧数组，每个关键帧对象包含以下字段：
| 字段名 | 类型 | 必填 | 描述 |
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| segment_id | string | 是 | 目标片段的唯一标识ID |
| property | string | 是 | 动画属性类型，支持的类型见下表 |
| offset | number | 是 | 关键帧在片段中的时间偏移（0-1范围，0表示开始，1表示结束） |
| value | number | 是 | 属性在该时间点的值 |
| segment_id | string | ✅ | 目标片段的唯一标识ID |
| property | string | ✅ | 动画属性类型，支持的类型见下表 |
| offset | number | ✅ | 关键帧在片段中的时间偏移（0-1范围，0表示开始，1表示结束） |
| value | number | ✅ | 属性在该时间点的值 |
### 支持的动画属性类型
#### 支持的动画属性类型
| 属性类型 | 描述 | 值范围 | 示例 |
|---------|------|--------|------|
@@ -56,9 +53,10 @@ keyframes 是一个JSON字符串，包含关键帧数组，每个关键帧对象
| 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",
@@ -69,62 +67,59 @@ keyframes 是一个JSON字符串，包含关键帧数组，每个关键帧对象
### 响应字段说明
| 字段名 | 类型 | 描述 |
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 草稿URL |
| draft_url | string | 更新后的草稿URL |
| keyframes_added | integer | 添加的关键帧数量 |
| affected_segments | array | 受影响的片段ID列表 |
### 错误响应
### 错误响应 (4xx/5xx)
```json
{
"code": 2013,
"message": "无效的关键帧信息，请检查keyframes字段值是否正确"
"detail": "错误信息描述"
}
```
## 使用示例
### cURL 示例
#### 1. 基本关键帧添加
```bash
curl -X POST "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_keyframes" \
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",
"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}]"
}'
```
### Python 示例
```python
import requests
import json
#### 2. 多属性关键帧
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())
```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
@@ -133,39 +128,27 @@ print(response.json())
4. **属性值范围**: 不同的属性类型有不同的值范围限制
5. **重复关键帧**: 相同片段相同属性的关键帧会被累加，不会覆盖
6. **性能考虑**: 单次请求建议不超过100个关键帧
7. **缩放属性**: 设置KFTypeScaleX或KFTypeScaleY会自动取消锁定XY轴缩放比例
## 错误码说明
## 工作流程
| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 2001 | 无效的草稿URL | 草稿URL格式错误或草稿不存在 |
| 2013 | 无效的关键帧信息 | keyframes字段格式错误或包含无效数据 |
| 2014 | 关键帧添加失败 | 添加关键帧过程中发生错误 |
| 2015 | 片段未找到 | 指定的segment_id在草稿中不存在 |
| 2016 | 无效的片段类型 | 该片段不支持关键帧功能 |
| 2017 | 无效的关键帧属性类型 | 指定的property类型不受支持 |
---
1. 验证必填参数（draft_url, keyframes）
2. 解析关键帧数据JSON字符串
3. 从缓存中获取草稿
4. 验证每个关键帧数据的有效性
5. 查找目标片段并验证片段类型
6. 为每个关键帧创建关键帧列表并添加到片段
7. 保存草稿
8. 返回添加结果信息
## 相关接口
- [create_draft](./create_draft.md) - 创建新的剪映草稿
- [add_videos](./add_videos.md) - 向草稿添加视频内容
- [save_draft](./save_draft.md) - 保存草稿更改
- [get_draft](./get_draft.md) - 获取草稿详情
## 技术实现
### 文件结构
- `src/service/add_keyframes.py` - 关键帧添加服务
- `src/schemas/add_keyframes.py` - 请求响应数据模型
- `src/pyJianYingDraft/keyframe.py` - 关键帧核心实现
### 核心逻辑
1. **参数验证**: 验证草稿URL、关键帧数据格式和属性类型
2. **片段检查**: 确认目标片段存在且支持关键帧功能
3. **关键帧添加**: 将关键帧数据写入草稿文件
4. **结果返回**: 返回添加的关键帧数量和受影响的片段
- [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)
---