> ## 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.

# 오디오 업로드

> 오디오 파일을 업로드하고 오디오 관련 API에서 사용할 URL을 가져옵니다

<Note>
  **중국 본토 사용자 안내:** 중국 본토 사용자는 `https://toapis.cn` 을 API 엔드포인트 (Base URL)로 사용해 주세요. 이 문서의 예시에서 `https://toapis.com` 을 `https://toapis.cn` 으로 바꿔 주세요.
</Note>

<Note>
  **문서 Playground는 파일 업로드를 지원하지 않습니다:** 테스트할 때는 아래의 cURL, Python 또는 JavaScript 예시를 사용해 주세요.
</Note>

## 오디오를 먼저 업로드하는 이유

1. **입력 방식 통일** - 로컬 오디오를 한 번 업로드하고 반환된 공개 URL을 재사용할 수 있습니다
2. **반복 전송 감소** - 동일한 오디오를 여러 요청에서 재사용할 수 있습니다

## Authorizations

<ParamField header="Authorization" type="string" required>
  Bearer Token으로 인증합니다

  API Key는 [API Key 관리 페이지](https://toapis.com/console/token)에서 확인할 수 있습니다

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="file" type="file" required>
  오디오 파일

  **지원 형식:**

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

  **제한:**

  * 최대 파일 크기: 50MB
</ParamField>

<ParamField body="purpose" type="string">
  업로드 목적 (선택 사항)

  기본값: `generation`
</ParamField>

## 응답

<ResponseField name="success" type="boolean">
  요청 성공 여부
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="응답 data">
    <ResponseField name="id" type="string">
      추적을 위한 업로드 레코드 ID
    </ResponseField>

    <ResponseField name="url" type="string">
      업로드된 오디오의 공개 URL
    </ResponseField>

    <ResponseField name="mime_type" type="string">
      오디오 MIME 타입, 예: `audio/mpeg`
    </ResponseField>

    <ResponseField name="size" type="integer">
      파일 크기 (바이트)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```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);
  })();
  ```
</RequestExample>

<ResponseExample>
  ```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"
  }
  ```
</ResponseExample>