> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 上傳音頻

> 上傳音頻獲取 URL, 用於音頻相關接口

> [!NOTE]
>
> **中國大陸用戶請注意:** 中國大陸用戶請使用 `https://toapis.cn` 作為接口地址 (Base URL).文檔示例中的 `https://toapis.com` 請替換為 `https://toapis.cn`.

> [!NOTE]
>
> **文檔 Playground 不支持文件上傳**: 請使用下方的 cURL,Python 或 JavaScript 代碼示例進行測試.

## 爲什麼需要先上傳音頻?

1. **統一輸入方式** - 本地音頻先上傳成公網 URL, 便於後續接口複用
2. **減少重複傳輸** - 上傳一次後可以在多個請求中重複使用

## Authorizations

**Authorization** `string` *required*

使用 Bearer Token 進行認證

獲取 API Key: 訪問 [API Key 管理頁面](https://toapis.com/console/token)

```
Authorization: Bearer YOUR_API_KEY
```

## Body

**file** `file` *required*

音頻文件

**支持的格式:**

* MP3 (.mp3)
* WAV (.wav)
* M4A (.m4a)

**限制:**

* 最大文件大小: 50MB

**purpose** `string`

上傳目的 (可選)

默認值: `generation`

## Response

**success** `boolean`

請求是否成功

**data** `object`

**返回數據**

**id** `string`

上傳記錄 ID, 用於追蹤

**url** `string`

音頻的公開訪問 URL

**mime\_type** `string`

音頻的 MIME 類型, 如 `audio/mpeg`

**size** `integer`

音頻文件大小 (字節)

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/uploads/audios \
  --header 'Authorization: Bearer <token>' \
  --form 'file=@/path/to/your/audio.mp3'
```

```python Python theme={null}
import requests

with open('audio.mp3', 'rb') as f:
    response = requests.post(
        "https://toapis.com/v1/uploads/audios",
        headers={
            "Authorization": "Bearer your-ToAPIs-key"
        },
        files={
            "file": f
        }
    )

result = response.json()
audio_url = result['data']['url']
print(f"音頻 URL: {audio_url}")
```

```javascript JavaScript theme={null}
(async () => {
const fileInput = document.createElement('input');
fileInput.type = 'file';
fileInput.accept = 'audio/mpeg,audio/wav,audio/mp4';
fileInput.click();
await new Promise(resolve => fileInput.onchange = resolve);

const formData = new FormData();
formData.append('file', fileInput.files[0]);

const uploadResponse = await fetch('https://toapis.com/v1/uploads/audios', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-ToAPIs-key'
  },
  body: formData
});

const uploadResult = await uploadResponse.json();
console.log('上傳結果:', uploadResult);
})();
```

```json 200 成功 theme={null}
{
  "success": true,
  "message": "",
  "data": {
    "id": "upload_abc12345",
    "url": "https://files.toapis.com/uploads/123/audios/1737568800_abc12345.mp3",
    "mime_type": "audio/mpeg",
    "size": 1892345
  }
}
```

```json 400 錯誤請求 theme={null}
{
  "success": false,
  "message": "Unsupported or invalid audio file. Allowed: MP3, WAV, M4A"
}
```

```json 400 文件過大 theme={null}
{
  "success": false,
  "message": "Audio too large. Maximum size is 50MB"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.