---
url: /docs/add_audios.md
description: Batch-add audios. audio_infos is a JSON string; times are microseconds.
---

# ADD\_AUDIOS API Documentation

## 🌐 Language Switch

[中文版](/docs/add_audios.zh) | [English](/docs/add_audios)

## Interface Information

```
POST /openapi/capcut-mate/v1/add_audios
```

## Function Description

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.

Pass draft\_url from create\_draft. audio\_infos must be a JSON string, not an object array. start/end are microseconds.

## Request Parameters

```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\":1.0,\"audio_effect\":\"reverb\"}]"
}
```

### Parameter Description

| 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 Array Structure

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 |

### Parameter Details

#### Time Parameters

* **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 Control

* **volume**: Audio volume size
  * 1.0 = Original volume
  * 0.5 = Half volume
  * 0.0 = Mute
  * Range: 0.0 - 2.0

#### Audio Effects

* **audio\_effect**: Audio effect name
  * None = No audio effect
  * Example: `"reverb"` (reverb effect)

## Response Format

### Success Response (200)

```json
{
  "code": 0,
  "message": "success",
  "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"]
}
```

### Response Field Description

| Field | Type | Description |
|-------|------|-------------|
| draft\_url | string | Updated draft URL |
| track\_id | string | Audio track ID |
| audio\_ids | array | List of added audio IDs |

### Error Response

```json
{
  "code": 2007,
  "message": "Invalid audio information, please check if the value of the audio_infos field is correct."
}
```

## Usage Examples

### cURL Examples

#### 1. Basic Audio Addition

```bash
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}]"
  }'
```

#### 2. Batch Adding Multiple Audios

```bash
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}]"
  }'
```

#### 3. Audio with Fade In/Out Effects

```bash
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 Description

| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 1001 | Parameter validation failed | Request body failed schema validation, e.g. `audio_infos` is not valid JSON, is not a list, or an `audio_url` does not start with `http://` / `https://` | Check parameter types and required fields |
| 2001 | Invalid draft URL | `draft_url` is missing, malformed, or the draft is not in the cache | Pass the `draft_url` returned by `create_draft` |
| 2005 | Download file failed | The audio file could not be downloaded from `audio_url` | Check that the audio URL is publicly accessible |
| 2007 | Invalid audio information | `audio_infos` is not valid JSON, an item is missing `audio_url`/`start`/`end`, `start` is negative, `end` is not greater than `start`, or `duration` is not positive | Fix the JSON string and the required fields |
| 2008 | Audio addition failed | Failed while adding the audio segment or saving the draft | Check the draft state and retry |
| 2042 | Draft lock acquisition timeout | Only one operation is allowed on a draft at a time | Retry later |

## Notes

1. **JSON Format**: audio\_infos must be a valid JSON string
2. **Time Unit**: All time parameters use microseconds (1 second = 1,000,000 microseconds)
3. **Audio Format**: Ensure audio file format is supported (e.g., MP3, WAV, AAC, etc.)
4. **File Size**: Large audio files may affect processing speed
5. **Network Access**: Audio URL must be accessible
6. **Volume Range**: Volume value must be within 0.0-2.0 range
7. **Track Limitation**: Audio overlap may occur in the same time period

## Workflow

1. Validate required parameters (draft\_url, audio\_infos)
2. Parse audio\_infos JSON string
3. Validate parameter configuration for each audio
4. Obtain and decrypt draft content
5. Create audio track
6. Add audio segments to track
7. Apply volume and audio effects
8. Save and encrypt draft
9. Return processing result

## Related Interfaces

* [Create Draft](/docs/create_draft)
* [Add Videos](/docs/add_videos)
* [Add Images](/docs/add_images)
* [Save Draft](/docs/save_draft)
* [Generate Video](/docs/gen_video)

***

📚 **Project Resources**\
**GitHub**: <https://github.com/Hommy-master/capcut-mate>\
**Gitee**: <https://gitee.com/taohongmin-gitee/capcut-mate>