POST /openapi/capcut-mate/v1/add_audios
Batch add audio materials to existing drafts. This interface supports adding multiple audio files to Jianying drafts, creating background music, sound effects, narration and other audio content for videos. Audio will be added to separate audio tracks without affecting video content.
📖 For more detailed documentation and tutorials, please visit: https://docs.jcaigc.cn
{
"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\":1.0,\"audio_effect\":\"reverb\"}]"
}| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| draft_url | string | ✅ | - | Complete URL of the target draft |
| audio_infos | string | ✅ | - | JSON string of audio information array |
audio_infos is a JSON string that resolves to an array, with each element containing the following fields:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| audio_url | string | ✅ | - | URL address of the audio file |
| start | number | ✅ | - | Audio start playback time (microseconds) |
| end | number | ✅ | - | Audio end playback time (microseconds) |
| duration | number | ❌ | Automatically obtained | Total audio duration (microseconds), automatically obtained if not provided |
| volume | number | ❌ | 1.0 | Volume size (0.0-2.0) |
| audio_effect | string | ❌ | None | Audio effect name |
- start: Start time of the audio on the timeline, unit microseconds (1 second = 1,000,000 microseconds)
- end: End time of the audio on the timeline, unit microseconds
- duration: Total duration of the audio file, used for material creation, unit microseconds, automatically obtained if not provided
- Playback Duration: Actual playback duration = end - start
- volume: Audio volume size
- 1.0 = Original volume
- 0.5 = Half volume
- 0.0 = Mute
- Range: 0.0 - 2.0
- audio_effect: Audio effect name
- None = No audio effect
- Example:
"reverb"(reverb effect)
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"track_id": "audio-track-uuid",
"audio_ids": ["audio1-uuid", "audio2-uuid", "audio3-uuid"]
}| Field | Type | Description |
|---|---|---|
| draft_url | string | Updated draft URL |
| track_id | string | Audio track ID |
| audio_ids | array | List of added audio IDs |
{
"detail": "Error message description"
}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/bgm.mp3\",\"start\":0,\"end\":10000000,\"duration\":15000000,\"volume\":0.8}]"
}'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},{\"audio_url\":\"https://assets.jcaigc.cn/bgm.mp3\",\"start\":3000000,\"end\":30000000,\"duration\":35000000,\"volume\":0.6}]"
}'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,\"audio_effect\":\"reverb\"}]"
}'| Error Code | Error Message | Description | Solution |
|---|---|---|---|
| 400 | draft_url is required | Missing draft URL parameter | Provide a valid draft URL |
| 400 | audio_infos is required | Missing audio information parameter | Provide valid audio information JSON |
| 400 | audio_infos format error | JSON format is incorrect | Check JSON string format |
| 400 | Audio configuration validation failed | Audio parameters do not meet requirements | Check parameters for each audio |
| 400 | audio_url is required | Audio URL missing | Provide URL for each audio |
| 400 | Time range invalid | end must be greater than start | Ensure end time is greater than start time |
| 400 | Volume value invalid | volume not in 0.0-2.0 range | Use volume value between 0.0-2.0 |
| 404 | Draft does not exist | Specified draft URL invalid | Check if draft URL is correct |
| 404 | Audio resource does not exist | Audio URL inaccessible | Check if audio URL is accessible |
| 500 | Audio processing failed | Internal processing error | Contact technical support |
- JSON Format: audio_infos must be a valid JSON string
- Time Unit: All time parameters use microseconds (1 second = 1,000,000 microseconds)
- Audio Format: Ensure audio file format is supported (e.g., MP3, WAV, AAC, etc.)
- File Size: Large audio files may affect processing speed
- Network Access: Audio URL must be accessible
- Volume Range: Volume value must be within 0.0-2.0 range
- Track Limitation: Audio overlap may occur in the same time period
- Validate required parameters (draft_url, audio_infos)
- Parse audio_infos JSON string
- Validate parameter configuration for each audio
- Obtain and decrypt draft content
- Create audio track
- Add audio segments to track
- Apply volume and audio effects
- Save and encrypt draft
- Return processing result
📚 Project Resources
GitHub: https://github.com/Hommy-master/capcut-mate
Gitee: https://gitee.com/taohongmin-gitee/capcut-mate