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 22:47:49 +08:00
parent a9fbdd69ac
commit b17ad90b49
1 changed files with 18 additions and 471 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/add_audios.md
+18 -471
View File
@@ -1,19 +1,6 @@
# ADD_AUDIOS API 接口文档
## 📋 目录
- [🔧 接口信息](#-接口信息)
- [🎯 功能描述](#-功能描述)
- [📥 请求参数](#-请求参数)
- [📤 响应格式](#-响应格式)
- [💻 使用示例](#-使用示例)
- [❌ 错误码说明](#-错误码说明)
- [⚠️ 注意事项](#️-注意事项)
- [🔄 工作流程](#-工作流程)
- [➡️ 下一步操作](#️-下一步操作)
- [🔗 相关接口](#-相关接口)
## 🔧 接口信息
## 接口信息
```
POST /openapi/capcut-mate/v1/add_audios
@@ -32,11 +19,11 @@ POST /openapi/capcut-mate/v1/add_audios
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"audio_infos": "[{\"audio_url\":\"https://assets.jcaigc.cn/audio1.mp3\",\"start\":0,\"end\":5000000,\"duration\":10000000,\"volume\":0.8,\"fade_in\":1000000,\"fade_out\":1000000}]"
"audio_infos": "[{\"audio_url\":\"https://assets.jcaigc.cn/audio1.mp3\",\"start\":0,\"end\":5000000,\"duration\":10000000,\"volume\":1.0,\"audio_effect\":\"reverb\"}]"
}
```
### 主要参数
### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
@@ -53,9 +40,8 @@ audio_infos是一个JSON字符串，解析后为数组，每个元素包含以
| start | number | ✅ | - | 音频开始播放时间(微秒) |
| end | number | ✅ | - | 音频结束播放时间(微秒) |
| duration | number | ✅ | - | 音频总时长(微秒) |
| volume | number | ❌ | 1.0 | 音量大小(0-1) |
| fade_in | number | ❌ | 0 | 淡入时长(微秒) |
| fade_out | number | ❌ | 0 | 淡出时长(微秒) |
| volume | number | ❌ | 1.0 | 音量大小(0.0-2.0) |
| audio_effect | string | ❌ | None | 音频效果名称 |
### 参数详解
@@ -72,17 +58,13 @@ audio_infos是一个JSON字符串，解析后为数组，每个元素包含以
- 1.0 = 原始音量
- 0.5 = 一半音量
- 0.0 = 静音
- 范围：0.0 - 1.0
- 范围：0.0 - 2.0
#### 淡入淡出效果
#### 音频效果
- **fade_in**: 淡入效果时长
- 0 = 无淡入效果
- 建议范围：500,000 - 3,000,000微秒（0.5-3秒）
- **fade_out**: 淡出效果时长
- 0 = 无淡出效果
- 建议范围：500,000 - 3,000,000微秒（0.5-3秒）
- **audio_effect**: 音频效果名称
- None = 无音频效果
- 示例：`"reverb"`（混响效果）
## 响应格式
@@ -134,7 +116,7 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"audio_infos": "[{\"audio_url\":\"https://assets.jcaigc.cn/intro.mp3\",\"start\":0,\"end\":3000000,\"duration\":5000000,\"volume\":1.0,\"fade_in\":500000},{\"audio_url\":\"https://assets.jcaigc.cn/bgm.mp3\",\"start\":3000000,\"end\":30000000,\"duration\":35000000,\"volume\":0.6}]"
"audio_infos": "[{\"audio_url\":\"https://assets.jcaigc.cn/intro.mp3\",\"start\":0,\"end\":3000000,\"duration\":5000000,\"volume\":1.0},{\"audio_url\":\"https://assets.jcaigc.cn/bgm.mp3\",\"start\":3000000,\"end\":30000000,\"duration\":35000000,\"volume\":0.6}]"
}'
```
@@ -145,446 +127,10 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"audio_infos": "[{\"audio_url\":\"https://assets.jcaigc.cn/outro.mp3\",\"start\":25000000,\"end\":30000000,\"duration\":8000000,\"volume\":0.9,\"fade_in\":1000000,\"fade_out\":2000000}]"
"audio_infos": "[{\"audio_url\":\"https://assets.jcaigc.cn/outro.mp3\",\"start\":25000000,\"end\":30000000,\"duration\":8000000,\"volume\":0.9,\"audio_effect\":\"reverb\"}]"
}'
```
### JavaScript 示例
```javascript
const addAudios = async (draftUrl, audioConfig) => {
const response = await fetch('/openapi/capcut-mate/v1/add_audios', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
draft_url: draftUrl,
...audioConfig
})
});
return response.json();
};
// 基本音频添加
const basicAudio = {
audio_infos: JSON.stringify([
{
audio_url: "https://assets.jcaigc.cn/bgm.mp3",
start: 0,
end: 10000000,
duration: 15000000,
volume: 0.8
}
])
};
// 音频序列
const audioSequence = {
audio_infos: JSON.stringify([
{
audio_url: "https://assets.jcaigc.cn/intro.mp3",
start: 0,
end: 3000000,
duration: 5000000,
volume: 1.0,
fade_in: 500000
},
{
audio_url: "https://assets.jcaigc.cn/main-bgm.mp3",
start: 2000000,
end: 25000000,
duration: 30000000,
volume: 0.6
},
{
audio_url: "https://assets.jcaigc.cn/outro.mp3",
start: 24000000,
end: 28000000,
duration: 6000000,
volume: 0.9,
fade_out: 1500000
}
])
};
// 音效组合
const soundEffects = {
audio_infos: JSON.stringify([
{
audio_url: "https://assets.jcaigc.cn/applause.mp3",
start: 5000000,
end: 8000000,
duration: 4000000,
volume: 0.7
},
{
audio_url: "https://assets.jcaigc.cn/transition.mp3",
start: 12000000,
end: 13500000,
duration: 2000000,
volume: 0.5
}
])
};
try {
const result1 = await addAudios(draftUrl, basicAudio);
const result2 = await addAudios(draftUrl, audioSequence);
const result3 = await addAudios(draftUrl, soundEffects);
console.log('音频添加成功:', {
basic: result1,
sequence: result2,
effects: result3
});
} catch (error) {
console.error('添加失败:', error);
}
```
### 高级JavaScript示例
```javascript
class AudioManager {
constructor(baseUrl = 'https://capcut-mate.jcaigc.cn') {
this.baseUrl = baseUrl;
}
async addAudios(draftUrl, audioConfig) {
const response = await fetch(`${this.baseUrl}/openapi/capcut-mate/v1/add_audios`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
draft_url: draftUrl,
...audioConfig
})
});
return response.json();
}
// 创建背景音乐
createBackgroundMusic(audioUrl, totalDuration, volume = 0.6, loop = false) {
const audios = [];
if (loop) {
// 循环播放逻辑
let currentTime = 0;
while (currentTime < totalDuration) {
audios.push({
audio_url: audioUrl,
start: currentTime,
end: Math.min(currentTime + 30000000, totalDuration), // 假设30秒循环
duration: 30000000,
volume: volume
});
currentTime += 30000000;
}
} else {
audios.push({
audio_url: audioUrl,
start: 0,
end: totalDuration,
duration: totalDuration,
volume: volume
});
}
return {
audio_infos: JSON.stringify(audios)
};
}
// 创建音频序列
createAudioSequence(audioList, crossFadeDuration = 1000000) {
const audios = [];
let currentTime = 0;
audioList.forEach((audio, index) => {
const audioInfo = {
audio_url: audio.url,
start: currentTime,
end: currentTime + audio.playDuration,
duration: audio.totalDuration,
volume: audio.volume || 1.0
};
// 添加交叉淡入淡出
if (index > 0) {
audioInfo.fade_in = crossFadeDuration;
// 调整前一个音频的淡出
if (audios[index - 1]) {
audios[index - 1].fade_out = crossFadeDuration;
}
}
// 最后一个音频淡出
if (index === audioList.length - 1) {
audioInfo.fade_out = audio.fadeOut || crossFadeDuration;
}
audios.push(audioInfo);
currentTime += audio.playDuration - (index > 0 ? crossFadeDuration : 0);
});
return {
audio_infos: JSON.stringify(audios)
};
}
// 创建音效轨道
createSoundEffects(effects) {
const audios = effects.map(effect => ({
audio_url: effect.url,
start: effect.startTime,
end: effect.startTime + effect.duration,
duration: effect.duration,
volume: effect.volume || 0.7,
fade_in: effect.fadeIn || 0,
fade_out: effect.fadeOut || 0
}));
return {
audio_infos: JSON.stringify(audios)
};
}
// 创建旁白音频
createNarration(narrationList) {
const audios = narrationList.map(narration => ({
audio_url: narration.url,
start: narration.startTime,
end: narration.startTime + narration.duration,
duration: narration.duration,
volume: narration.volume || 0.9,
fade_in: 200000, // 0.2秒淡入
fade_out: 200000 // 0.2秒淡出
}));
return {
audio_infos: JSON.stringify(audios)
};
}
// 批量处理音频
async batchProcessAudios(draftUrl, audioConfigs) {
const results = [];
for (const config of audioConfigs) {
try {
const result = await this.addAudios(draftUrl, config);
results.push(result);
// 添加延迟避免请求过快
await new Promise(resolve => setTimeout(resolve, 100));
} catch (error) {
console.error('音频处理失败:', error);
results.push({ error: error.message });
}
}
return results;
}
}
// 使用示例
const audioManager = new AudioManager();
// 创建背景音乐
const bgm = audioManager.createBackgroundMusic(
"https://assets.jcaigc.cn/bgm.mp3",
60000000, // 60秒
0.6,
true // 循环播放
);
// 创建音频序列
const sequence = audioManager.createAudioSequence([
{
url: "https://assets.jcaigc.cn/intro.mp3",
playDuration: 5000000,
totalDuration: 5000000,
volume: 1.0
},
{
url: "https://assets.jcaigc.cn/main.mp3",
playDuration: 20000000,
totalDuration: 25000000,
volume: 0.8
},
{
url: "https://assets.jcaigc.cn/outro.mp3",
playDuration: 3000000,
totalDuration: 3000000,
volume: 1.0,
fadeOut: 2000000
}
]);
// 创建音效
const effects = audioManager.createSoundEffects([
{
url: "https://assets.jcaigc.cn/whoosh.mp3",
startTime: 10000000,
duration: 1500000,
volume: 0.5
},
{
url: "https://assets.jcaigc.cn/ding.mp3",
startTime: 25000000,
duration: 1000000,
volume: 0.8
}
]);
// 批量处理
await audioManager.batchProcessAudios(draftUrl, [bgm, sequence, effects]);
```
### Python 示例
```python
import requests
import json
from typing import List, Dict, Optional
class AudioProcessor:
def __init__(self, base_url="https://capcut-mate.jcaigc.cn"):
self.base_url = base_url
def add_audios(self, draft_url: str, audio_config: Dict) -> Dict:
response = requests.post(
f'{self.base_url}/openapi/capcut-mate/v1/add_audios',
headers={'Content-Type': 'application/json'},
json={
"draft_url": draft_url,
**audio_config
}
)
return response.json()
def create_background_music(self, audio_url: str, total_duration: int,
volume: float = 0.6, loop: bool = False) -> Dict:
"""创建背景音乐"""
audios = []
if loop:
current_time = 0
audio_duration = 30000000 # 假设30秒循环
while current_time < total_duration:
end_time = min(current_time + audio_duration, total_duration)
audios.append({
"audio_url": audio_url,
"start": current_time,
"end": end_time,
"duration": audio_duration,
"volume": volume
})
current_time += audio_duration
else:
audios.append({
"audio_url": audio_url,
"start": 0,
"end": total_duration,
"duration": total_duration,
"volume": volume
})
return {"audio_infos": json.dumps(audios)}
def create_audio_sequence(self, audio_list: List[Dict],
cross_fade_duration: int = 1000000) -> Dict:
"""创建音频序列"""
audios = []
current_time = 0
for i, audio in enumerate(audio_list):
audio_info = {
"audio_url": audio["url"],
"start": current_time,
"end": current_time + audio["play_duration"],
"duration": audio["total_duration"],
"volume": audio.get("volume", 1.0)
}
# 添加交叉淡入淡出
if i > 0:
audio_info["fade_in"] = cross_fade_duration
if audios:
audios[-1]["fade_out"] = cross_fade_duration
# 最后一个音频淡出
if i == len(audio_list) - 1:
audio_info["fade_out"] = audio.get("fade_out", cross_fade_duration)
audios.append(audio_info)
current_time += audio["play_duration"] - (cross_fade_duration if i > 0 else 0)
return {"audio_infos": json.dumps(audios)}
def create_sound_effects(self, effects: List[Dict]) -> Dict:
"""创建音效轨道"""
audios = []
for effect in effects:
audios.append({
"audio_url": effect["url"],
"start": effect["start_time"],
"end": effect["start_time"] + effect["duration"],
"duration": effect["duration"],
"volume": effect.get("volume", 0.7),
"fade_in": effect.get("fade_in", 0),
"fade_out": effect.get("fade_out", 0)
})
return {"audio_infos": json.dumps(audios)}
# 使用示例
processor = AudioProcessor()
# 背景音乐
bgm_config = processor.create_background_music(
"https://assets.jcaigc.cn/bgm.mp3",
60000000, # 60秒
volume=0.6,
loop=True
)
# 音频序列
sequence_config = processor.create_audio_sequence([
{
"url": "https://assets.jcaigc.cn/intro.mp3",
"play_duration": 5000000,
"total_duration": 5000000,
"volume": 1.0
},
{
"url": "https://assets.jcaigc.cn/main.mp3",
"play_duration": 20000000,
"total_duration": 25000000,
"volume": 0.8
}
])
# 音效
effects_config = processor.create_sound_effects([
{
"url": "https://assets.jcaigc.cn/whoosh.mp3",
"start_time": 10000000,
"duration": 1500000,
"volume": 0.5
}
])
# 添加到草稿
draft_url = "YOUR_DRAFT_URL"
results = []
for config in [bgm_config, sequence_config, effects_config]:
result = processor.add_audios(draft_url, config)
results.append(result)
print(f"音频添加成功: {result['track_id']}")
```
## 错误码说明
| 错误码 | 错误信息 | 说明 | 解决方案 |
@@ -595,7 +141,7 @@ for config in [bgm_config, sequence_config, effects_config]:
| 400 | 音频配置验证失败 | 音频参数不符合要求 | 检查每个音频的参数 |
| 400 | audio_url是必填项 | 音频URL缺失 | 为每个音频提供URL |
| 400 | 时间范围无效 | end必须大于start | 确保结束时间大于开始时间 |
| 400 | 音量值无效 | volume不在0-1范围内 | 使用0-1之间的音量值 |
| 400 | 音量值无效 | volume不在0.0-2.0范围内 | 使用0.0-2.0之间的音量值 |
| 404 | 草稿不存在 | 指定的草稿URL无效 | 检查草稿URL是否正确 |
| 404 | 音频资源不存在 | 音频URL无法访问 | 检查音频URL是否可访问 |
| 500 | 音频处理失败 | 内部处理错误 | 联系技术支持 |
@@ -607,9 +153,8 @@ for config in [bgm_config, sequence_config, effects_config]:
3. **音频格式**: 确保音频文件格式被支持（如MP3、WAV、AAC等）
4. **文件大小**: 大音频文件可能影响处理速度
5. **网络访问**: 音频URL必须可以正常访问
6. **音量范围**: 音量值必须在0.0-1.0范围内
7. **淡入淡出**: 淡入淡出时长不能超过音频播放时长
8. **轨道限制**: 同一时间段可能存在音频重叠
6. **音量范围**: 音量值必须在0.0-2.0范围内
7. **轨道限制**: 同一时间段可能存在音频重叠
## 工作流程
@@ -619,7 +164,7 @@ for config in [bgm_config, sequence_config, effects_config]:
4. 获取并解密草稿内容
5. 创建音频轨道
6. 添加音频片段到轨道
7. 应用音量和淡入淡出效果
7. 应用音量和音频效果
8. 保存并加密草稿
9. 返回处理结果
@@ -631,6 +176,8 @@ for config in [bgm_config, sequence_config, effects_config]:
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)
---
<div align="right">
📚 **项目资源**