ADD_EFFECTS API 接口文檔

接口信息

POST /openapi/capcut-mate/v1/add_effects

功能描述

向現有草稿中添加視頻特效。該接口用於在指定的時間段內添加特效素材到剪映草稿中，支持多種特效類型如邊框特效、濾鏡特效、動態特效等。特效可以用於增強視頻的視覺效果。

更多文檔

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

請求參數

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "effect_infos": "[{\"effect_title\": \"錄製邊框 III\", \"start\": 0, \"end\": 5000000}, {\"effect_title\": \"復古濾鏡\", \"start\": 2000000, \"end\": 7000000}]"
}

參數説明

參數詳解

effect_infos 字段格式

effect_infos 是一個JSON字符串，包含特效信息數組，每個特效對象包含以下字段：

[
    {
        "effect_title": "錄製邊框 III",  // 特效名稱/標題，必選參數
        "start": 0,                     // 特效開始時間（微秒），必選參數  
        "end": 5000000                  // 特效結束時間（微秒），必選參數
    }
]

字段説明:

• effect_title: 特效名稱，必須是系統中已存在的特效名稱
• start: 特效開始時間，單位為微秒，必須大於等於0
• end: 特效結束時間，單位為微秒，必須大於start

時間參數

• start: 特效在時間軸上的開始時間，單位為微秒（1秒 = 1,000,000微秒）
• end: 特效在時間軸上的結束時間，單位為微秒
• duration: 特效顯示時長 = end - start

特效名稱説明

• effect_title: 特效的名稱

  • 格式：字符串
  • 示例："錄製邊框 III"
  • 獲取方式：通過剪映特效庫或相關API獲取

  • 常見特效名稱：

    • 邊框特效："錄製邊框 III", "簡約邊框", "霓虹邊框"
    • 濾鏡特效："復古濾鏡", "黑白濾鏡", "暖色調"
    • 動態特效："粒子效果", "光暈效果", "閃爍特效"
    • 轉場特效："淡入淡出", "推拉門", "馬賽克轉場"

響應格式

成功響應 (200)

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "track_id": "effect_track_123",
  "effect_ids": ["effect_001", "effect_002"],
  "segment_ids": ["seg_001", "seg_002"]
}

響應字段説明

錯誤響應 (4xx/5xx)

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

使用示例

cURL 示例

1. 基本特效添加

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_effects \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "effect_infos": "[{\"effect_title\": \"錄製邊框 III\", \"start\": 0, \"end\": 5000000}]"
  }'

2. 批量特效添加

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_effects \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "effect_infos": "[{\"effect_title\": \"錄製邊框 III\", \"start\": 0, \"end\": 5000000}, {\"effect_title\": \"復古濾鏡\", \"start\": 2000000, \"end\": 7000000}]"
  }'

錯誤碼説明

注意事項

1. 時間單位: 所有時間參數使用微秒（1秒 = 1,000,000微秒）
2. 特效名稱: 確保使用有效的特效名稱
3. 時間範圍: end必須大於start
4. 軌道管理: 系統自動創建特效軌道
5. 性能考慮: 避免同時添加大量特效

工作流程

1. 驗證必填參數（draft_url, effect_infos）
2. 檢查時間範圍的有效性
3. 從緩存中獲取草稿
4. 創建特效軌道（如果不存在）
5. 解析特效信息並創建特效片段
6. 添加片段到軌道
7. 保存草稿
8. 返回特效信息

相關接口

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

<div align="right">

📚 項目資源
GitHub搜索capcut-mate就能找到。

</div>