ADD_EFFECTS API 接口文档
接口信息
- 请求方式: POST
- 接口地址:
/openapi/capcut-tools/v1/add_effects
功能描述
向现有草稿中添加视频特效。该接口用于在指定的时间段内添加特效素材到剪映草稿中，支持多种特效类型如边框特效、滤镜特效、动态特效等。特效可以用于增强视频的视觉效果。
更多文档: 📖 速创 AIGC-工具平台官方文档
请求参数
{
"draft_url": "https://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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,000,000 微秒）
- 特效名称: 确保使用有效的特效名称
- 时间范围: end 必须大于 start
- 轨道管理: 系统自动创建特效轨道
- 性能考虑: 避免同时添加大量特效
工作流程
- 验证必填参数（draft_url, effect_infos）
- 检查时间范围的有效性
- 从缓存中获取草稿
- 创建特效轨道（如果不存在）
- 解析特效信息并创建特效片段
- 添加片段到轨道
- 保存草稿
- 返回特效信息
相关接口
- 创建草稿
- 添加视频
- 添加音频
- 添加图片
- 保存草稿
- 生成视频