---
url: /docs/audio_infos.md
---
# AUDIO\_INFOS API Documentation

## 🌐 Language Switch

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

## Interface Information

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

## Function Description

Generate audio information based on audio URLs and timelines. This interface converts audio file URLs and timeline configurations into the audio information format required by Jianying drafts, supporting volume control and audio effect settings.

## Request Parameters

```json
{
  "mp3_urls": ["https://assets.jcaigc.cn/audio1.mp3", "https://assets.jcaigc.cn/audio2.mp3"],
  "timelines": [
    {"start": 0, "end": 3000000},
    {"start": 3000000, "end": 8000000}
  ],
  "audio_effect": "reverb",
  "volume": 0.8
}
```

### Parameter Description

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| mp3\_urls | array\[string] |✅ | - | Audio file URL array |
| timelines | array\[object] |✅ | - | Timeline configuration array |
| audio\_effect | string |❌ | None | Audio effect name |
| volume | number |❌ | None | Volume level (0.0-2.0) |

### Parameter Details

#### mp3\_urls

* **Type**: array\[string]
* **Description**: Array of audio file URL addresses
* **Example**: \["https://assets.jcaigc.cn/bgm.mp3", "https://assets.jcaigc.cn/sfx.mp3"]

#### timelines

* **Type**: array\[object]
* **Description**: Timeline configuration array, each element contains start and end fields
* **Example**: \[{"start": 0, "end": 5000000}, {"start": 5000000, "end": 10000000}]

#### audio\_effect

* **Type**: string
* **Description**: Audio effect name
* **Default**: None
* **Example**: "reverb", "echo", "bass\_boost"

#### volume

* **Type**: number
* **Description**: Audio volume level
* **Default**: None
* **Range**: 0.0 - 2.0
* **Example**: 0.8 (80% volume)

## Response Format

### Success Response (200)

```json
{
  "code": 0,
  "message": "success",
  "infos": "[{\"audio_url\":\"https://assets.jcaigc.cn/audio1.mp3\",\"start\":0,\"end\":3000000,\"audio_effect\":\"reverb\",\"volume\":0.8},{\"audio_url\":\"https://assets.jcaigc.cn/audio2.mp3\",\"start\":3000000,\"end\":8000000,\"audio_effect\":\"reverb\",\"volume\":0.8}]"
}
```

### Response Field Description

| Field | Type | Description |
|-------|------|-------------|
| infos | string | Audio information JSON string |

### Error Response

```json
{
  "code": 1001,
  "message": "Parameter validation failed"
}
```

## Usage Examples

### cURL Examples

#### 1. Basic Audio Information Generation

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/audio_infos \
  -H "Content-Type: application/json" \
  -d '{
    "mp3_urls": ["https://assets.jcaigc.cn/bgm.mp3"],
    "timelines": [{"start": 0, "end": 10000000}],
    "volume": 0.7
  }'
```

#### 2. Audio Information with Effects

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/audio_infos \
  -H "Content-Type: application/json" \
  -d '{
    "mp3_urls": ["https://assets.jcaigc.cn/intro.mp3", "https://assets.jcaigc.cn/content.mp3"],
    "timelines": [{"start": 0, "end": 2000000}, {"start": 2000000, "end": 12000000}],
    "audio_effect": "reverb",
    "volume": 0.9
  }'
```

## Error Code Description

| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 1001 | Parameter validation failed | Request body failed schema validation (`mp3_urls`/`timelines` missing, timeline item lacking `start`/`end`, or wrong types) | Check parameter types and required fields |

## Notes

1. **Array Matching**: if `mp3_urls` and `timelines` lengths differ, the shorter length is used (no hard error)
2. **Time Unit**: All time parameters use microseconds (1 second = 1,000,000 microseconds)
3. **Volume Range**: volume value must be between 0.0-2.0
4. **Effect Support**: audio\_effect needs to be a supported audio effect name
5. **JSON Format**: Returned infos is a JSON string that needs to be parsed before use
6. **Network Access**: Audio URLs must be accessible

## Workflow

1. Validate required parameters (mp3\_urls, timelines)
2. Align the two arrays by the shorter length
3. Validate timeline parameter validity
4. Read the optional volume and audio\_effect parameters
5. Generate corresponding audio information for each audio URL
6. Apply volume and audio effect settings
7. Convert information to JSON string format
8. Return processing result

## Related Interfaces

* [Create Draft](/docs/create_draft)
* [Add Audios](/docs/add_audios)
* [Audio Timelines](/docs/audio_timelines)
* [Save Draft](/docs/save_draft)

***

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

### Language Switch

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