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

# 음성 클로닝

> Chatterbox HD로 짧은 참조 오디오 샘플에서 음성을 클로닝한 다음 Venice Audio API를 통해 음성을 생성하세요.

음성 클로닝을 사용하면 짧은 참조 오디오 샘플에서 제공되는 음성으로 발화를 생성할 수 있습니다. `tts-chatterbox-hd`를 사용하면 샘플을 `/audio/voices`에 업로드하고, 반환된 `vv_...` voice handle을 저장한 다음, 그 handle을 `/audio/speech`에 전달합니다.

<Note>
  Voice handle은 모델별로 구분됩니다. `tts-chatterbox-hd`로 생성된 handle은 반드시 `tts-chatterbox-hd`와 함께 사용해야 합니다.
</Note>

## 동작 방식

1. **업로드** — 깨끗한 참조 오디오 파일을 `POST /audio/voices`로 전송합니다
2. **저장** — 반환된 `id` voice handle을 저장합니다
3. **생성** — `POST /audio/speech`에서 handle을 `voice`로 전송합니다

## 사전 준비 사항

* Venice API 키
* MP3, WAV, FLAC 또는 M4A 포맷의 깨끗한 참조 샘플
* 한 명의 화자가 명확하게 말하는 최소 5\~10초 분량의 오디오

API 키를 설정하세요:

```bash theme={"system"}
export VENICE_API_KEY="your-api-key"
```

## 1단계: 음성 샘플 업로드

참조 오디오를 multipart form data로 업로드하여 voice handle을 생성합니다:

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/voices \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "model=tts-chatterbox-hd" \
  -F "file=@./reference-voice.wav"
```

**응답 (200):**

```json theme={"system"}
{
  "id": "vv_voice_abc123xyz",
  "model": "tts-chatterbox-hd"
}
```

음성 생성을 위해 `id`를 저장하세요:

```bash theme={"system"}
export VENICE_VOICE_ID="vv_voice_abc123xyz"
```

## 2단계: 음성 생성

클로닝된 voice handle을 speech 요청의 `voice`로 전달합니다:

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-chatterbox-hd",
    "voice": "'"$VENICE_VOICE_ID"'",
    "input": "Hello from Venice. This audio is generated with a cloned Chatterbox HD voice.",
    "response_format": "mp3"
  }' \
  --output chatterbox-clone.mp3
```

응답 본문은 요청한 포맷의 바이너리 오디오입니다.

***

## 전체 예제

이 예제는 참조 샘플을 업로드하고, `jq`로 voice handle을 추출한 다음, 생성된 오디오를 `chatterbox-clone.mp3`에 기록합니다:

```bash theme={"system"}
VOICE_ID=$(
  curl -s https://api.venice.ai/api/v1/audio/voices \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -F "model=tts-chatterbox-hd" \
    -F "file=@./reference-voice.wav" | jq -r '.id'
)

curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-chatterbox-hd",
    "voice": "'"$VOICE_ID"'",
    "input": "This is a complete Chatterbox HD voice cloning example.",
    "response_format": "mp3",
    "speed": 1
  }' \
  --output chatterbox-clone.mp3
```

## 음성 샘플 팁

한 명의 화자, 최소한의 배경 소음, 음악이 없는 샘플을 사용하세요. 속삭이거나, 노래하거나, 과도하게 처리된 오디오보다 자연스러운 발화가 더 잘 작동합니다.

음성에 독특한 페이싱, 억양 또는 어조가 있는 경우 더 긴 샘플이 도움이 될 수 있지만, 샘플은 대상 화자에 집중시키세요.

## Handle 만료

Chatterbox HD 클로닝은 zero-shot 방식입니다: Venice는 업로드된 참조 오디오를 일시적으로 저장하고, 음성을 합성할 때 모델이 이를 읽습니다. 영구적인 음성 템플릿은 생성되지 않습니다.

Voice handle은 7일 후 자동으로 만료됩니다. Handle이 만료된 후에는 참조 샘플을 다시 업로드하여 새로운 `vv_...` handle을 생성하세요.

## 클로닝 지원 확인

클로닝을 지원하는 모델은 모델 사양에 `voice_cloning` 객체를 포함합니다. 지원되는 포맷, 최소 샘플 길이 및 보관 기간을 확인하려면 TTS 모델을 조회하세요:

```bash theme={"system"}
curl "https://api.venice.ai/api/v1/models?type=tts" \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

`tts-chatterbox-hd`는 다음과 같이 표시됩니다:

```json theme={"system"}
{
  "voice_cloning": {
    "mode": "zero_shot",
    "accepted_formats": ["mp3", "wav", "flac", "m4a"],
    "min_sample_seconds": 5,
    "retention_days": 7
  }
}
```

***

## API 파라미터

### 음성 생성

| Field   | Type   | Required | Description                            |
| ------- | ------ | -------- | -------------------------------------- |
| `model` | string | 예        | `tts-chatterbox-hd`여야 함                |
| `file`  | file   | 예        | 참조 오디오 샘플. 지원 포맷은 MP3, WAV, FLAC, M4A. |

### 발화 생성

| Field             | Type    | Required | Default | Description                                          |
| ----------------- | ------- | -------- | ------- | ---------------------------------------------------- |
| `model`           | string  | 예        | -       | Voice handle 생성에 사용된 모델과 일치해야 함                      |
| `voice`           | string  | 예        | -       | `POST /audio/voices`가 반환한 `vv_...` handle            |
| `input`           | string  | 예        | -       | 합성할 텍스트, 최대 4096자                                    |
| `response_format` | string  | 아니오      | `mp3`   | `mp3`, `opus`, `aac`, `flac`, `wav` 또는 `pcm`         |
| `speed`           | number  | 아니오      | `1`     | `0.25`에서 `4.0` 사이의 발화 속도                             |
| `temperature`     | number  | 아니오      | -       | `0`에서 `2` 사이의 샘플링 temperature. 값이 높을수록 변형이 추가될 수 있음. |
| `streaming`       | boolean | 아니오      | `false` | 문장 단위로 오디오 스트리밍                                      |

## 일반적인 오류

| Status | Cause                                    | Fix                                                          |
| ------ | ---------------------------------------- | ------------------------------------------------------------ |
| `400`  | 지원되지 않는 오디오 컨테이너 또는 호환되지 않는 voice handle | MP3, WAV, FLAC 또는 M4A를 사용하고 handle을 생성에 사용한 동일 모델과 함께 사용하세요. |
| `401`  | API 키 누락 또는 잘못됨                          | `Authorization: Bearer $VENICE_API_KEY`를 전송하세요.              |
| `402`  | 잔액 부족                                    | Venice 잔액을 충전하세요.                                            |
| `413`  | 업로드된 파일이 너무 큼                            | 더 짧거나 더 압축된 참조 샘플을 사용하세요.                                    |
| `429`  | 속도 제한 초과                                 | 속도 제한 윈도가 리셋된 후 다시 시도하세요.                                    |