From 7d9a7d288a1fc9eef511064e24f261b5b4152e20 Mon Sep 17 00:00:00 2001 From: Hommy <16620803786@163.com> Date: Mon, 1 Dec 2025 22:58:27 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=E6=96=87=E6=A1=A3=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/add_keyframes.md | 163 +++++++++++++++++++----------------------- 1 file changed, 73 insertions(+), 90 deletions(-) diff --git a/docs/add_keyframes.md b/docs/add_keyframes.md index b623373..8886b88 100644 --- a/docs/add_keyframes.md +++ b/docs/add_keyframes.md @@ -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) ---