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

# 커스텀 보이스 사용하기

> 오디오 샘플로 보이스를 클로닝한 뒤, 프리셋 보이스와 동일하게 TTS 호출에서 사용합니다.

<Note>
  이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/docs/examples/custom-voice-tts)을 함께 확인해 주세요.
</Note>

커스텀 보이스는 계정에 귀속된 보이스 클론입니다. 한 번 등록하고 나면 프리셋 보이스와 동일하게 동작합니다 — 동일한 `text_to_speech` 엔드포인트, 동일한 파라미터, 동일한 응답 형태를 사용합니다.

이 예제는 전체 흐름을 안내합니다. 오디오 샘플을 업로드하고, 커스텀 보이스 목록을 확인한 뒤, 새 클론으로 음성을 생성합니다.

<Note>
  API를 통한 보이스 클로닝은 Free 플랜에서는 제공되지 않습니다. 샘플 오디오는 **WAV 또는 MP3 형식, 3MB 미만**이어야 하며, 보이스 이름은 **100자 이하**여야 합니다.
</Note>

## 1단계 — 샘플로 보이스 클로닝하기

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    import os
    from supertone import Supertone

    with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client:
        with open("voice_sample.wav", "rb") as f:
            response = client.custom_voices.create_cloned_voice(
                files={"file_name": "voice_sample.wav", "content": f.read()},
                name="Hana — narrator voice",
                description="Calm, mid-pitch female voice for audiobook narration.",
            )

        print("Created custom voice:", response.voice_id)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    import { Supertone } from "@supertone/supertone";
    import * as fs from "node:fs";

    const client = new Supertone({ apiKey: process.env.SUPERTONE_API_KEY });

    const audio = fs.readFileSync("voice_sample.wav");

    const response = await client.customVoices.createClonedVoice({
      files: {
        fileName: "voice_sample.wav",
        content: audio,
      },
      name: "Hana — narrator voice",
      description: "Calm, mid-pitch female voice for audiobook narration.",
    });

    console.log("Created custom voice:", response.voiceId);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"dark"}
    curl -X POST "https://supertoneapi.com/v1/custom-voices/cloned-voice" \
      -H "x-sup-api-key: $SUPERTONE_API_KEY" \
      -F "files=@voice_sample.wav" \
      -F "name=Hana — narrator voice" \
      -F "description=Calm, mid-pitch female voice for audiobook narration."
    ```
  </Tab>
</Tabs>

응답에는 새 `voice_id`가 포함됩니다. 이 값을 저장해 두세요 — TTS 호출에 그대로 전달하면 됩니다.

## 2단계 — 커스텀 보이스 목록 확인하기

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    result = client.custom_voices.list_custom_voices(page_size=20)
    for voice in result.items or []:
        print(voice.voice_id, voice.name, voice.description)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    const result = await client.customVoices.listCustomVoices({ pageSize: 20 });
    for (const voice of result.items ?? []) {
      console.log(voice.voiceId, voice.name, voice.description);
    }
    ```
  </Tab>
</Tabs>

이름이나 설명으로 필터링하려면 `search_custom_voices`를 사용하세요.

## 3단계 — 새 보이스로 음성 생성하기

```python theme={"dark"}
response = client.text_to_speech.create_speech(
    voice_id=NEW_VOICE_ID,
    text="The first chapter begins on a quiet rainy morning.",
    language="en",
    model="sona_speech_2",
)

with open("speech.wav", "wb") as f:
    f.write(response.result.read())
```

커스텀 보이스는 프리셋 보이스와 마찬가지로 `voice_settings`, `output_format`, `include_phonemes`, `normalized_text` 필드를 모두 지원합니다.

## 4단계 — 수정 또는 삭제

```python theme={"dark"}
# Rename or update the description
client.custom_voices.edit_custom_voice(
    voice_id=NEW_VOICE_ID,
    name="Hana — narrator (v2)",
    description="Improved take with cleaner room tone.",
)

# Permanently delete
client.custom_voices.delete_custom_voice(voice_id=NEW_VOICE_ID)
```

## 팁

* **동일 계정에서만 사용 가능.** 클론드 보이스는 해당 보이스를 생성한 계정에서만 호출할 수 있습니다. 다른 계정과 `voice_id`를 공유하면 `403 Forbidden`이 반환됩니다.
* **플랫폼 간 동기화.** [Supertone Play](https://play.supertone.ai)에서 클로닝한 보이스는 `list_custom_voices`에 자동으로 나타납니다. 반대로도 마찬가지입니다 — API에서 클로닝한 보이스는 Play에서도 보입니다.
* **샘플 품질.** 깨끗하고 모노, 단일 화자로 녹음된 5\~30초 분량의 오디오에서 최상의 클론이 만들어집니다. 배경 음악, 여러 명의 목소리, 심한 룸 노이즈는 피하세요.
* **권한과 고지 의무.** 업로드하는 모든 보이스에 대해 클로닝 권리를 확보해 주세요. AI 생성 음성에 관한 해당 관할 지역의 규정과 고지 의무를 반드시 확인하세요.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Create cloned voice" icon="microphone" href="/ko/api-reference/endpoints/create-cloned-voice">
    전체 업로드 스키마와 제약 조건입니다.
  </Card>

  <Card title="보이스" icon="users" href="/ko/docs/core-concepts/voices">
    프리셋 보이스와 커스텀 보이스가 어떻게 함께 사용되는지 살펴보세요.
  </Card>
</CardGroup>