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

# 생성된 음성 다운로드

> 본인 소유의 음성 생성물에 대한 새로운 임시 다운로드 URL을 조회합니다. 생성이 시작되거나 미디어 크레딧이 사용되지 않습니다.

본인 소유의 음성 생성물에 대한 새로운 임시 다운로드 URL을 조회합니다. 생성이 시작되거나 미디어 크레딧이 사용되지 않습니다.

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/tts_download
```

## 인증 및 권한

<ParamField header="x-api-key" type="string" required>
  이 헤더에 VoiceCheap API 키를 전달하세요. 동일한 API 키를 사용하는 Authorization: Bearer도 지원합니다. OAuth 액세스 토큰은 MCP에서만 허용되며, 이
  REST 엔드포인트에서는 사용할 수 없습니다.
</ParamField>

필요한 권한: `tts:read`.

활성 유료 구독이 필요합니다. 권한은 팀 역할, 리소스 소유권, 미디어 크레딧 또는 요금제 한도를 변경하지 않습니다.

## 매개변수

<ParamField body="historyId" type="string" required>
  tts\_generate 또는 tts\_list가 반환한 이력 ID입니다.

  패턴: `^(free-)?[0-9a-f]{64}$`.
</ParamField>

<Accordion title="전체 입력 스키마">
  아래 JSON Schema는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다.

  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "historyId": {
        "type": "string",
        "pattern": "^(free-)?[0-9a-f]{64}$",
        "description": "History ID returned by tts_generate or tts_list."
      }
    },
    "required": ["historyId"],
    "additionalProperties": false
  }
  ```
</Accordion>

## 요청 예제

예제의 리소스 식별자와 미디어 키를 계정에서 반환된 값으로 바꾸세요. 동일한 변경 작업을 재시도할 때는 요청 식별자를 유지하세요.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_download' \
    --header "x-api-key: $VOICECHEAP_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{"historyId":"722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"}'
  ```

  ```javascript JavaScript theme={null}
  const input = {
    historyId: '722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d',
  };
  const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_download', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.VOICECHEAP_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  });
  const body = await response.json();
  if (!response.ok) throw new Error(body.code + ': ' + body.message);
  console.log(body);
  ```

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

  response = requests.post(
      "https://api.voicecheap.ai/v1/actions/tts_download",
      headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
      json={"historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"},
      timeout=120,
  )
  body = response.json()
  if not response.ok:
      raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
  print(body)
  ```
</RequestExample>

## 응답

성공한 첫 실행은 작업 결과를 data 아래에 포함하여 HTTP 200을 반환합니다. 재전송 시에는 저장된 요청 상태를 대신 반환할 수 있습니다. 예제는 지원되는 응답 중 하나를 보여주며 모든 선택 필드를 포함하지는 않습니다.

소유한 음성 합성 MP3의 새 임시 다운로드 URL입니다.

<ResponseExample>
  ```json HTTP 200 theme={null}
  {
    "data": {
      "downloadUrl": "https://files.example.com/launch-script-speech.mp3"
    }
  }
  ```
</ResponseExample>

## 결과 필드

| 필드 | 설명 |
| - | - |
| `data.downloadUrl` | 이 이력 항목의 임시 MP3 다운로드 URL입니다. |

## 작업 참고 사항

* 이 조회는 음성을 생성하거나 미디어 생성 크레딧을 소모하지 않습니다. 연동 호출 한도는 계속 적용됩니다.
* 파일명은 sourceFileName이 있으면 해당 값에서 파생되며, 없으면 voicecheap-tts-speech.mp3입니다. URL은 임시 URL입니다.
* 음성 합성 기록과 사용자 지정 음성은 인증된 계정에 속합니다. 팀 결제를 사용해도 다른 멤버의 음성 합성 결과나 음성에 접근할 수 없습니다.

## 사용량

성공한 호출마다 월간 API/MCP 호출 1회가 차감됩니다. 미디어 크레딧과 해당 작업의 생성 허용량도 적용됩니다.

## 오류

| HTTP 상태 | 코드 | 의미 또는 복구 방법 |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | 자격 증명이 access\_token 또는 api\_key 쿼리 매개변수로 제공되었습니다. 자격 증명은 헤더로 보내세요. |
| 400 | `VALIDATION_ERROR` | 입력이 액션 스키마와 일치하지 않습니다. 필드 오류는 details를 확인하세요. |
| 401 | `API_KEY_EXPIRED` | API 키가 만료되었습니다. |
| 401 | `INVALID_API_KEY` | 유효하고 만료되지 않은 API 키를 제공하세요. |
| 401 | `INVALID_CREDENTIAL` | Authorization 헤더의 형식이 잘못되었거나 x-api-key와 충돌합니다. |
| 401 | `MISSING_CREDENTIAL` | 사용 가능한 헤더 자격 증명이 전달되지 않았거나 4096자를 초과했습니다. |
| 401 | `USER_NOT_FOUND` | 이 자격 증명에 연결된 계정이 더 이상 존재하지 않습니다. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | 이 자격 증명의 사용자가 둘 이상의 팀에 속해 있어 청구 컨텍스트가 모호합니다. |
| 403 | `INSUFFICIENT_SCOPE` | 필요한 모든 권한을 부여하거나 다른 자격 증명을 사용하세요. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | 계정의 통합 한도를 확인할 수 없습니다. |
| 403 | `SUBSCRIPTION_REQUIRED` | 활성 유료 구독을 사용하세요. |
| 403 | `TEAM_OWNER_NOT_FOUND` | 실제로 적용되는 팀 소유자 계정을 찾을 수 없습니다. |
| 404 | `TEXT_TO_SPEECH_HISTORY_NOT_FOUND` | 음성 기록 항목이 존재하지 않거나 다른 계정에 속합니다. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | 월간 한도가 초기화될 때까지 기다리거나 요금제를 변경하세요. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Retry-After가 있으면 지정된 시간만큼 기다리고 백오프를 적용하세요. |
| 500 | `INTERNAL_ERROR` | 변경 작업을 재시도하기로 결정하기 전에 저장된 요청 상태와 리소스 기록을 확인하세요. |
| 503 | `SERVER_RESTARTING` | 서버가 다시 시작 중입니다. 잠시 후 재시도하고, 변경 작업의 경우 동일한 요청 식별자를 유지하세요. |

```json theme={null}
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": ["tts:read"]
  }
}
```


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