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

# 커스텀 보이스

> 내 계정에 등록하고 관리하는 보이스 클론 — 생성, 조회, 검색, 수정, 삭제까지.

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

**커스텀 보이스(custom voice)** 는 내 계정에 연결된 보이스 클론입니다. 한 번 등록되면 프리셋 보이스와 동일하게 동작합니다 — 같은 TTS 엔드포인트, 같은 파라미터를 사용하지만, 별도의 엔드포인트에 존재하며 해당 보이스를 생성한 계정에서만 호출할 수 있습니다.

커스텀 보이스는 두 가지 방법으로 생성할 수 있습니다.

* **[Supertone Play](https://play.supertone.ai)에서 생성** — 샘플을 업로드하고 UI를 통해 클로닝합니다.
* **API로 생성** — 오디오 파일과 함께 `POST /v1/custom-voices/cloned-voice`를 호출합니다.

두 방법 모두 동일한 종류의 보이스를 생성합니다. Play에서 클로닝한 보이스는 `list_custom_voices`에 나타나고, API로 클로닝한 보이스는 Play에 나타납니다. 별도의 동기화 단계는 없습니다.

<Note>
  **API를 통한** 보이스 클로닝은 Free 등급에서 지원되지 않습니다. Play에서의 클로닝은 모든 유료 등급에서 사용 가능합니다.
</Note>

## 엔드포인트 개요

| Endpoint                              | Purpose                     |
| ------------------------------------- | --------------------------- |
| `POST /v1/custom-voices/cloned-voice` | 업로드한 오디오 샘플로 새 클론을 생성합니다.   |
| `GET /v1/custom-voices`               | 계정의 모든 커스텀 보이스를 조회합니다.      |
| `GET /v1/custom-voices/search`        | 이름 또는 설명으로 커스텀 보이스를 필터링합니다. |
| `GET /v1/custom-voices/{voice_id}`    | 단일 커스텀 보이스를 조회합니다.          |
| `PATCH /v1/custom-voices/{voice_id}`  | 이름 또는 설명을 수정합니다.            |
| `DELETE /v1/custom-voices/{voice_id}` | 커스텀 보이스를 영구 삭제합니다.          |

## 클론 생성하기

클로닝하려는 보이스의 깨끗한 오디오 샘플을 업로드하세요.

<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 호출에 전달할 값이므로 저장해 두세요.

### 업로드 제약사항

* **포맷:** WAV 또는 MP3
* **크기:** 3 MB 미만
* **이름:** 최대 100자

깨끗하고 단일 화자인 모노 오디오(5–30초)가 가장 좋은 클로닝 결과를 만듭니다. 배경 음악, 여러 명의 음성, 심한 룸 노이즈는 피하세요.

## 조회 및 검색

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

    # Search by name or description
    result = client.custom_voices.search_custom_voices(name="narrator")
    ```
  </Tab>

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

    // Search by name or description
    const search = await client.customVoices.searchCustomVoices({ name: "narrator" });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"dark"}
    # List all
    curl "https://supertoneapi.com/v1/custom-voices?page_size=20" \
      -H "x-sup-api-key: $SUPERTONE_API_KEY"

    # Search
    curl "https://supertoneapi.com/v1/custom-voices/search?name=narrator" \
      -H "x-sup-api-key: $SUPERTONE_API_KEY"
    ```
  </Tab>
</Tabs>

## TTS에서 커스텀 보이스 사용하기

클론이 등록되면, 프리셋 보이스와 동일하게 `text_to_speech.create_speech`를 호출하면 됩니다. 커스텀 `voice_id`만 전달하세요.

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

커스텀 보이스는 프리셋 보이스와 동일한 `voice_settings`, `output_format`, `include_phonemes`, `normalized_text` 필드를 지원합니다.

## 수정 또는 삭제

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

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

```typescript theme={"dark"}
// Rename / update description
await client.customVoices.editCustomVoice({
  voiceId: CUSTOM_VOICE_ID,
  name: "Hana — narrator (v2)",
  description: "Improved take with cleaner room tone.",
});

// Permanently delete
await client.customVoices.deleteCustomVoice({ voiceId: CUSTOM_VOICE_ID });
```

## 중요 제약사항

* **계정 범위 제한.** 커스텀 보이스는 이를 생성한 계정에서만 호출할 수 있습니다. ID를 알고 있더라도 다른 사람의 커스텀 보이스를 호출하면 `403 Forbidden`이 반환됩니다.
* **동일한 크레딧.** 커스텀 보이스 호출도 프리셋 보이스와 동일한 비율로 크레딧이 차감됩니다.
* **권한 및 고지.** 업로드하는 모든 보이스를 클로닝할 권리가 있는지 반드시 확인하세요. AI 생성 음성과 최종 사용자 고지에 관한 본인 관할 지역의 규정을 확인하세요.

## 관련 문서

<CardGroup cols={2}>
  <Card title="프리셋 보이스" icon="users" href="/ko/docs/core-concepts/voices">
    Supertone의 프리셋 보이스 라이브러리를 탐색하고 검색하세요.
  </Card>

  <Card title="엔드투엔드 예제" icon="lightbulb" href="/ko/docs/examples/custom-voice-tts">
    커스텀 보이스를 클로닝, 조회하고 TTS에서 사용하는 예제입니다.
  </Card>

  <Card title="API 레퍼런스" icon="book-open" href="/ko/api-reference/endpoints/create-cloned-voice">
    요청과 응답의 전체 스키마를 확인하세요.
  </Card>

  <Card title="비용 및 사용량" icon="credit-card" href="/ko/docs/production/cost-and-usage">
    비용을 예측하고 보이스별 사용량을 모니터링하세요.
  </Card>
</CardGroup>