# ADD_EFFECTS API 接口文档

## 接口信息

```bash
POST /openapi/capcut-mate/v1/add_effects
```

## 功能描述

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

## 更多文档

📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)

## 请求参数

```json
{
  "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字符串，包含特效信息数组，每个特效对象包含以下字段：

```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)

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

```json
{
  "detail": "错误信息描述"
}
```

## 使用示例

### cURL 示例

#### 1. 基本特效添加

```bash
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. 批量特效添加

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

## 相关接口

- [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)

---

<div align="right">

📚 **项目资源**  
GitHub搜索capcut-mate就能找到。

</div>

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

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

音视频

开发工具

剪映API接口文档：通过add_effects接口为视频草稿添加特效，支持边框、滤镜等多种特效类型。提供详细参数说明、请求示例和错误处理方案，帮助开发者快速实现视频特效添加功能。

GitHub

JSON

文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【剪映小助手】向现有草稿中添加视频特效-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐