opensource/capcut-mate
3
0
Fork 0
mirror of https://github.com/Hommy-master/capcut-mate.git synced 2026-08-30 17:48:47 +08:00
Code Issues Packages Projects Releases Wiki Activity

优化文档。

Browse Source
This commit is contained in:
Hommy
2025-12-01 23:06:28 +08:00
parent 158a569aec
commit aaf8d5cd5b
1 changed files with 9 additions and 396 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/add_videos.md
+9 -396
View File
@@ -1,19 +1,6 @@
# ADD_VIDEOS API 接口文档
## 📋 目录
- [🔧 接口信息](#-接口信息)
- [🎯 功能描述](#-功能描述)
- [📥 请求参数](#-请求参数)
- [📤 响应格式](#-响应格式)
- [💻 使用示例](#-使用示例)
- [❌ 错误码说明](#-错误码说明)
- [⚠️ 注意事项](#️-注意事项)
- [🔄 工作流程](#-工作流程)
- [➡️ 下一步操作](#️-下一步操作)
- [🔗 相关接口](#-相关接口)
## 🔧 接口信息
## 接口信息
```
POST /openapi/capcut-mate/v1/add_videos
@@ -41,7 +28,7 @@ POST /openapi/capcut-mate/v1/add_videos
}
```
### 主要参数
### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
@@ -71,12 +58,14 @@ POST /openapi/capcut-mate/v1/add_videos
### 参数详解
#### 时间参数
- **start**: 视频在时间轴上的开始时间，单位微秒（1秒 = 1,000,000微秒）
- **end**: 视频在时间轴上的结束时间，单位微秒
- **duration**: 视频文件的总时长，用于素材创建
- **播放时长**: 实际播放时长 = end - start
#### 透明度参数
- **alpha**: 全局透明度，应用于所有添加的视频
- 1.0 = 完全不透明
- 0.5 = 半透明
@@ -84,16 +73,19 @@ POST /openapi/capcut-mate/v1/add_videos
- 范围：0.0 - 1.0
#### 缩放参数
- **scale_x/scale_y**: X/Y轴方向的缩放比例
- 1.0 = 原始大小，0.5 = 缩小一半，2.0 = 放大两倍
- 建议范围：0.1 - 5.0
#### 位置参数
- **transform_x/transform_y**: X/Y轴方向的位置偏移，单位像素
- 正值向右/下移动，负值向左/上移动
- 以画布中心为原点
#### 遮罩类型
支持的遮罩类型：
- `圆形` - 圆形遮罩效果
- `爱心` - 爱心形状遮罩
@@ -103,6 +95,7 @@ POST /openapi/capcut-mate/v1/add_videos
- `镜面` - 镜面反射遮罩
#### 转场效果
- **transition**: 转场效果名称
- **transition_duration**: 转场持续时间
- 最小值：100,000微秒（0.1秒）
@@ -110,6 +103,7 @@ POST /openapi/capcut-mate/v1/add_videos
- 推荐值：500,000微秒（0.5秒）
#### 音量控制
- **volume**: 视频音量大小
- 1.0 = 原始音量
- 0.5 = 一半音量
@@ -194,387 +188,6 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
}'
```
### JavaScript 示例
```javascript
const addVideos = async (draftUrl, videoConfig) => {
const response = await fetch('/openapi/capcut-mate/v1/add_videos', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
draft_url: draftUrl,
...videoConfig
})
});
return response.json();
};
// 基本视频添加
const basicVideos = {
video_infos: JSON.stringify([
{
video_url: "https://assets.jcaigc.cn/video1.mp4",
width: 1920,
height: 1080,
start: 0,
end: 5000000,
duration: 10000000
}
])
};
// 多视频序列
const videoSequence = {
video_infos: JSON.stringify([
{
video_url: "https://assets.jcaigc.cn/intro.mp4",
width: 1920,
height: 1080,
start: 0,
end: 3000000,
duration: 5000000,
transition: "淡入淡出",
transition_duration: 500000
},
{
video_url: "https://assets.jcaigc.cn/main.mp4",
width: 1920,
height: 1080,
start: 3000000,
end: 15000000,
duration: 20000000,
volume: 0.8
},
{
video_url: "https://assets.jcaigc.cn/outro.mp4",
width: 1920,
height: 1080,
start: 15000000,
end: 18000000,
duration: 5000000,
mask: "圆形"
}
]),
alpha: 1.0
};
// 画中画效果
const pipEffect = {
video_infos: JSON.stringify([
{
video_url: "https://assets.jcaigc.cn/background.mp4",
width: 1920,
height: 1080,
start: 0,
end: 10000000,
duration: 15000000
},
{
video_url: "https://assets.jcaigc.cn/overlay.mp4",
width: 640,
height: 360,
start: 2000000,
end: 8000000,
duration: 10000000,
mask: "圆形"
}
]),
scale_x: 0.8,
scale_y: 0.8,
transform_x: 200,
transform_y: -150,
alpha: 0.9
};
try {
const result1 = await addVideos(draftUrl, basicVideos);
const result2 = await addVideos(draftUrl, videoSequence);
const result3 = await addVideos(draftUrl, pipEffect);
console.log('视频添加成功:', {
basic: result1,
sequence: result2,
pip: result3
});
} catch (error) {
console.error('添加失败:', error);
}
```
### 高级JavaScript示例
```javascript
class VideoManager {
constructor(baseUrl = 'https://capcut-mate.jcaigc.cn') {
this.baseUrl = baseUrl;
}
async addVideos(draftUrl, videoConfig) {
const response = await fetch(`${this.baseUrl}/openapi/capcut-mate/v1/add_videos`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
draft_url: draftUrl,
...videoConfig
})
});
return response.json();
}
// 创建视频序列
createVideoSequence(videos, transitionType = "淡入淡出", transitionDuration = 500000) {
let currentTime = 0;
const videoInfos = videos.map((video, index) => {
const videoInfo = {
video_url: video.url,
width: video.width,
height: video.height,
start: currentTime,
end: currentTime + video.playDuration,
duration: video.totalDuration,
volume: video.volume || 1.0
};
// 添加转场效果（除了最后一个视频）
if (index < videos.length - 1) {
videoInfo.transition = transitionType;
videoInfo.transition_duration = transitionDuration;
}
// 添加遮罩效果
if (video.mask) {
videoInfo.mask = video.mask;
}
currentTime += video.playDuration;
return videoInfo;
});
return {
video_infos: JSON.stringify(videoInfos)
};
}
// 创建画中画效果
createPictureInPicture(mainVideo, overlayVideo, position = { x: 300, y: -200 }, scale = 0.3) {
const videoInfos = [
{
video_url: mainVideo.url,
width: mainVideo.width,
height: mainVideo.height,
start: 0,
end: mainVideo.duration,
duration: mainVideo.duration
},
{
video_url: overlayVideo.url,
width: overlayVideo.width,
height: overlayVideo.height,
start: overlayVideo.start || 0,
end: overlayVideo.end || overlayVideo.duration,
duration: overlayVideo.duration,
mask: overlayVideo.mask || "圆形"
}
];
return {
video_infos: JSON.stringify(videoInfos),
transform_x: position.x,
transform_y: position.y,
scale_x: scale,
scale_y: scale
};
}
// 创建分屏效果
createSplitScreen(videos, layout = "horizontal") {
const videoInfos = videos.map((video, index) => {
let transform_x = 0, transform_y = 0;
if (layout === "horizontal") {
// 水平分屏
const sectionWidth = 1 / videos.length;
transform_x = (index - (videos.length - 1) / 2) * sectionWidth * video.width;
} else if (layout === "vertical") {
// 垂直分屏
const sectionHeight = 1 / videos.length;
transform_y = (index - (videos.length - 1) / 2) * sectionHeight * video.height;
}
return {
video_url: video.url,
width: video.width,
height: video.height,
start: video.start || 0,
end: video.end || video.duration,
duration: video.duration
};
});
return {
video_infos: JSON.stringify(videoInfos)
};
}
}
// 使用示例
const videoManager = new VideoManager();
// 创建视频序列
const sequence = videoManager.createVideoSequence([
{
url: "https://assets.jcaigc.cn/intro.mp4",
width: 1920,
height: 1080,
playDuration: 3000000,
totalDuration: 5000000
},
{
url: "https://assets.jcaigc.cn/main.mp4",
width: 1920,
height: 1080,
playDuration: 10000000,
totalDuration: 15000000,
volume: 0.8
}
]);
// 创建画中画
const pip = videoManager.createPictureInPicture(
{
url: "https://assets.jcaigc.cn/background.mp4",
width: 1920,
height: 1080,
duration: 10000000
},
{
url: "https://assets.jcaigc.cn/overlay.mp4",
width: 640,
height: 360,
duration: 6000000,
start: 2000000,
end: 8000000,
mask: "圆形"
}
);
await videoManager.addVideos(draftUrl, sequence);
await videoManager.addVideos(draftUrl, pip);
```
### Python 示例
```python
import requests
import json
from typing import List, Dict
class VideoProcessor:
def __init__(self, base_url="https://capcut-mate.jcaigc.cn"):
self.base_url = base_url
def add_videos(self, draft_url: str, video_config: Dict) -> Dict:
response = requests.post(
f'{self.base_url}/openapi/capcut-mate/v1/add_videos',
headers={'Content-Type': 'application/json'},
json={
"draft_url": draft_url,
**video_config
}
)
return response.json()
def create_video_sequence(self, videos: List[Dict], transition_type: str = "淡入淡出") -> Dict:
current_time = 0
video_infos = []
for i, video in enumerate(videos):
video_info = {
"video_url": video["url"],
"width": video["width"],
"height": video["height"],
"start": current_time,
"end": current_time + video["play_duration"],
"duration": video["total_duration"],
"volume": video.get("volume", 1.0)
}
# 添加转场效果（除了最后一个）
if i < len(videos) - 1:
video_info["transition"] = transition_type
video_info["transition_duration"] = 500000
# 添加遮罩
if "mask" in video:
video_info["mask"] = video["mask"]
video_infos.append(video_info)
current_time += video["play_duration"]
return {
"video_infos": json.dumps(video_infos)
}
def create_picture_in_picture(self, main_video: Dict, overlay_video: Dict,
position: Dict = None, scale: float = 0.3) -> Dict:
if position is None:
position = {"x": 300, "y": -200}
video_infos = [
{
"video_url": main_video["url"],
"width": main_video["width"],
"height": main_video["height"],
"start": 0,
"end": main_video["duration"],
"duration": main_video["duration"]
},
{
"video_url": overlay_video["url"],
"width": overlay_video["width"],
"height": overlay_video["height"],
"start": overlay_video.get("start", 0),
"end": overlay_video.get("end", overlay_video["duration"]),
"duration": overlay_video["duration"],
"mask": overlay_video.get("mask", "圆形")
}
]
return {
"video_infos": json.dumps(video_infos),
"transform_x": position["x"],
"transform_y": position["y"],
"scale_x": scale,
"scale_y": scale
}
# 使用示例
processor = VideoProcessor()
# 视频序列
videos = [
{
"url": "https://assets.jcaigc.cn/intro.mp4",
"width": 1920,
"height": 1080,
"play_duration": 3000000,
"total_duration": 5000000
},
{
"url": "https://assets.jcaigc.cn/main.mp4",
"width": 1920,
"height": 1080,
"play_duration": 10000000,
"total_duration": 15000000,
"volume": 0.8
}
]
sequence_config = processor.create_video_sequence(videos)
result = processor.add_videos("YOUR_DRAFT_URL", sequence_config)
print(f"结果: {result}")
```
## 错误码说明
| 错误码 | 错误信息 | 说明 | 解决方案 |