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. 返回特效信息

相关接口

• 创建草稿
• 添加视频
• 添加音频
• 添加图片
• 保存草稿
• 生成视频