mirror of
https://github.com/Hommy-master/capcut-mate.git
synced 2026-09-01 15:32:57 +08:00
Hommy
176 lines
5.5 KiB
Markdown
176 lines
5.5 KiB
Markdown
# 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**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
|
||
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
|
||
|
||
</div> |