【剪映小助手】向现有草稿中添加视频特效

简介: 向现有草稿中添加视频特效。该接口用于在指定的时间段内添加特效素材到剪映草稿中,支持多种特效类型如边框特效、滤镜特效、动态特效等。特效可以用于增强视频的视觉效果。

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}]"
}

参数说明

参数名 类型 必填 默认值 说明
draft_url string ✅ - 目标草稿的完整URL
effect_infos string ✅ - 特效信息列表的JSON字符串

参数详解

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"]
}

响应字段说明

字段名 类型 说明
draft_url string 更新后的草稿URL
track_id string 特效轨道ID
effect_ids array 添加的特效ID列表
segment_ids array 创建的特效片段ID列表

错误响应 (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}]"
  }'

错误码说明

错误码 错误信息 说明 解决方案
400 draft_url是必填项 缺少草稿URL参数 提供有效的draft_url
400 effect_infos是必填项 缺少特效信息参数 提供有效的effect_infos
400 时间范围无效 end必须大于start 确保结束时间大于开始时间
400 无效的特效信息,请检查effect_infos字段值是否正确 特效参数校验失败 检查特效参数是否符合要求
404 草稿不存在 指定的草稿URL无效 检查草稿URL是否正确
404 特效不存在 指定的特效名称无效 确认特效名称是否正确
500 特效添加失败 内部处理错误 联系技术支持

注意事项

  1. 时间单位: 所有时间参数使用微秒(1秒 = 1,000,000微秒)
  2. 特效名称: 确保使用有效的特效名称
  3. 时间范围: end必须大于start
  4. 轨道管理: 系统自动创建特效轨道
  5. 性能考虑: 避免同时添加大量特效

工作流程

  1. 验证必填参数(draft_url, effect_infos)
  2. 检查时间范围的有效性
  3. 从缓存中获取草稿
  4. 创建特效轨道(如果不存在)
  5. 解析特效信息并创建特效片段
  6. 添加片段到轨道
  7. 保存草稿
  8. 返回特效信息

相关接口


相关文章
|
安全 Cloud Native Go
解决Gradle依赖问题:不安全协议的处理策略Could not resolve all dependencies for configuration ‘:detachedConfiguration9
解决Gradle依赖问题:不安全协议的处理策略Could not resolve all dependencies for configuration ‘:detachedConfiguration9
1990 0
|
8月前
|
API
开源剪映小助手(capcut-mate)v3.0.22发布
CapCut Mate API 是开源免费的剪映草稿自动化工具,基于 FastAPI,支持独立部署。为大模型提供开箱即用的视频编辑 Skills,实现剪映核心功能全流程自动化,轻松生成专业视频。兼容 Coze/n8n,支持云渲染。
1970 1
|
11月前
|
编解码 API Windows
【剪映小助手】提交视频生成任务
提交视频生成任务。该接口采用异步处理模式,立即返回任务提交状态,视频生成在后台进行。支持任务排队,确保系统稳定性。
|
11月前
|
存储 JSON 缓存
【剪映小助手】向现有草稿中批量添加字幕
向现有草稿中批量添加字幕。该接口用于在指定的时间段内添加字幕到剪映草稿中,支持丰富的字幕样式设置,包括文本颜色、边框颜色、对齐方式、透明度、字体、字体大小、字间距、行间距、缩放和位置调整等。
|
11月前
|
存储 缓存 API
【剪映小助手】向现有草稿中添加贴纸
向现有草稿中添加贴纸。该接口用于在指定的时间段内添加贴纸素材到剪映草稿中,支持贴纸的缩放和位置调整。贴纸可以用于增强视频的视觉效果,如表情、装饰、文字等。
|
11月前
|
API
【剪映小助手】查询视频生成任务的状态和进度
查询视频生成任务的状态和进度。配合 gen_video 接口使用,用于实时跟踪视频生成任务的执行情况,包括任务状态、进度百分比、完成结果等信息。
|
10月前
|
人工智能 监控 架构师
裁掉平庸的代码,留下AI agent指挥官:2026年架构师的生存手记
2026架构革命已来:67%架构师已引入AI Agent指挥官,代码量锐减90%,上线周期从6个月压缩至4周,维护成本降75%。AI Agent架构师成最稀缺岗位(供需比1:10),薪资高出40%。裁掉平庸代码,转向能力组装——这是架构师的生存必选项。
1118 3