---
url: /docs/get_audio_duration.md
---
# GET\_AUDIO\_DURATION API Documentation

## 🌐 Language Switch

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

## Interface Information

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

## Function Description

Get the duration of audio files, supporting various common audio formats. Use FFprobe tool for precise audio analysis, returning the accurate duration of audio files in microseconds.

## Request Parameters

```json
{
  "mp3_url": "https://assets.jcaigc.cn/audio/sample.mp3"
}
```

### Parameter Description

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| mp3\_url | string |✅ | - | Audio file URL, supporting mp3, wav, m4a and other common audio formats |

### Parameter Details

#### Audio URL Parameter

* **mp3\_url**: Complete URL address of the audio file
  * Supported formats: mp3, wav, aac, flac, m4a and other common audio formats
  * Need to ensure URL is accessible and file is complete

## Response Format

### Success Response (200)

```json
{
  "code": 0,
  "message": "success",
  "duration": 2325333
}
```

### Response Field Description

| Field | Type | Description |
|-------|------|-------------|
| duration | integer | Audio duration, unit: microseconds |

### Error Response

```json
{
  "code": 2034,
  "message": "Get audio duration failed"
}
```

## Usage Examples

### cURL Examples

#### 1. Basic Audio Duration Retrieval

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_audio_duration \
  -H "Content-Type: application/json" \
  -d '{
    "mp3_url": "https://assets.jcaigc.cn/audio/sample.mp3"
  }'
```

## Error Code Description

| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 1001 | Parameter validation failed | `mp3_url` is missing or not a valid URL | Provide a valid `mp3_url` |
| 2004 | File size exceeds the limit | The audio file exceeds the server download size limit | Use a smaller audio file |
| 2005 | Download file failed | The audio file could not be downloaded | Check that the audio URL is publicly accessible |
| 2034 | Get audio duration failed | Failed to read the audio duration | Check the audio file format |

## Notes

1. **Time Unit**: Returned duration uses microseconds (1 second = 1,000,000 microseconds)
2. **Audio Formats**: Support mp3, wav, aac, flac, m4a and other common audio formats
3. **File Size**: Recommended to control within reasonable range, overly large files may cause timeout
4. **Network Access**: Ensure provided audio URL can be accessed normally

## Workflow

1. Validate required parameter (mp3\_url)
2. Download audio file to temporary directory
3. Use ffprobe to analyze audio file and get duration
4. Clean up temporary files
5. Return audio duration information

## Related Interfaces

* [Add Audios](/docs/add_audios)
* [Add Videos](/docs/add_videos)
* [Create Draft](/docs/create_draft)

***

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