ADD_KEYFRAMES API 接口文檔

接口信息

POST /openapi/capcut-mate/v1/add_keyframes

功能描述

向現有草稿中添加關鍵幀。該接口用於在指定的片段上添加關鍵幀動畫，支持多種屬性類型的關鍵幀設置，如位置、縮放、旋轉、透明度等。關鍵幀可以用於創建複雜的動畫效果，增強視頻的視覺表現力。

更多文檔

📖 更多詳細文檔和教程請訪問：https://docs.jcaigc.cn

請求參數

{
  "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\":5000000,\"value\":-0.1}]"
}

參數説明

參數名	類型	必填	默認值	説明
draft_url	string	✅	-	目標草稿的完整URL
keyframes	string	✅	-	關鍵幀信息列表的JSON字符串

keyframes 參數詳解

基本結構

keyframes 是一個JSON字符串，包含關鍵幀數組，每個關鍵幀對象包含以下字段：

字段名	類型	必填	説明
segment_id	string	✅	目標片段的唯一標識ID
property	string	✅	動畫屬性類型，支持的類型見下表
offset	number	✅	關鍵幀在片段中的時間偏移（微秒絕對時間）
value	number	✅	屬性在該時間點的值

offset 參數説明

offset 參數只支持微秒絕對時間格式：

• 以微秒為單位的整數，如 5000000 表示片段開始後5秒的位置
• 系統會自動將微秒值轉換為相對時間比例

支持的動畫屬性類型

屬性類型	描述	值範圍	示例
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 (透明)
UNIFORM_SCALE	統一縮放	0.1 到 10.0	1.0 (原始), 0.5 (縮小), 2.0 (放大)
KFTypeSaturation	飽和度	-1.0 到 1.0	0.0 (原始), -0.5 (降低), 0.5 (增強)
KFTypeContrast	對比度	-1.0 到 1.0	0.0 (原始), -0.5 (降低), 0.5 (增強)
KFTypeBrightness	亮度	-1.0 到 1.0	0.0 (原始), -0.5 (變暗), 0.5 (變亮)
KFTypeVolume	音量	0.0 到 2.0	1.0 (原始), 0.5 (降低), 2.0 (增強)

響應格式

成功響應 (200)

{
  "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)

{
  "detail": "錯誤信息描述"
}

使用示例

cURL 示例

1. 基本關鍵幀添加（使用微秒時間）

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-id\",\"property\":\"UNIFORM_SCALE\",\"offset\":0,\"value\":1},{\"segment_id\":\"segment-id\",\"property\":\"UNIFORM_SCALE\",\"offset\":5000000,\"value\":1.3}]"
  }'

2. 多屬性關鍵幀

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\":2500000,\"value\":90},{\"segment_id\":\"segment-uuid\",\"property\":\"KFTypeAlpha\",\"offset\":5000000,\"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 值必須是非負整數（微秒）
4. 屬性值範圍: 不同的屬性類型有不同的值範圍限制
5. 重複關鍵幀: 相同片段相同屬性的關鍵幀會被累加，不會覆蓋
6. 性能考慮: 單次請求建議不超過100個關鍵幀
7. 縮放屬性: 設置KFTypeScaleX或KFTypeScaleY會自動取消鎖定XY軸縮放比例

工作流程

1. 驗證必填參數（draft_url, keyframes）
2. 解析關鍵幀數據JSON字符串
3. 從緩存中獲取草稿
4. 驗證每個關鍵幀數據的有效性
5. 查找目標片段並驗證片段類型
6. 為每個關鍵幀創建關鍵幀列表並添加到片段
7. 保存草稿
8. 返回添加結果信息

相關接口

• 創建草稿
• 添加視頻
• 添加音頻
• 添加圖片
• 保存草稿
• 生成視頻

---

📚 項目資源
GitHub: 搜索capcut-mate即可找到