> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-ce69695c.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 음성 클로닝

> Chatterbox HD로 참조 오디오에서 음성을 클로닝하고 voice handle을 저장해 Venice Audio API로 음성을 생성합니다.

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

<Note>
  Voice handle은 모델별로 구분됩니다. `tts-chatterbox-hd`로 생성된 handle은 반드시 `tts-chatterbox-hd`와 함께 사용해야 합니다. 보이스 클로닝은 참조 샘플을 기반으로 한 text-to-speech입니다. 기존 녹음을 다른 음성으로 다시 녹음하려면 대신 [보이스 체인저](/ko/guides/media/voice-changer) API를 사용하세요.
</Note>

## 동작 방식

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

## 사전 준비 사항

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

API 키를 설정하세요:

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

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

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

```bash theme={null}
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"
```

`curl -F`를 사용할 때는 `Content-Type`을 수동으로 설정하지 마세요. `curl`이 `multipart/form-data` 헤더와 필수 boundary를 자동으로 추가합니다.

**응답 (200):**

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

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

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

## 2단계: 음성 생성

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

```bash theme={null}
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."
  }' \
  --output chatterbox-clone.wav
```

응답 본문은 JSON이 아니라 모델의 기본 형식으로 된 바이너리 오디오입니다. `tts-chatterbox-hd`는 현재 WAV를 기본값으로 사용합니다.

***

## 전체 예제

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

```bash theme={null}
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.",
    "speed": 1
  }' \
  --output chatterbox-clone.wav
```

## 음성 샘플 팁

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

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

## Handle 만료

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

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

## 클로닝 지원 확인

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

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

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

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

***

## API 파라미터

### 음성 생성

| 필드 | 유형 | 필수 여부 | 설명 |
| - | - | - | - |
| `model` | string | 예 | `tts-chatterbox-hd`여야 함 |
| `file` | file | 예 | 참조 오디오 샘플. 지원 포맷은 MP3, WAV, FLAC 및 MP4. |

### 발화 생성

| 필드 | 유형 | 필수 여부 | 기본값 | 설명 |
| - | - | - | - | - |
| `model` | string | 예 | - | Voice handle 생성에 사용된 모델과 일치해야 함 |
| `voice` | string | 예 | - | `POST /audio/voices`가 반환한 `vv_...` handle |
| `input` | string | 예 | - | 합성할 텍스트, 최대 4096자 |
| `response_format` | string | 아니오 | 모델별 | 선택적 출력 형식 재정의. 설정하기 전에 모델의 지원 형식과 기본 형식을 확인하세요. |
| `speed` | number | 아니오 | `1` | `0.25`에서 `4.0` 사이의 발화 속도 |
| `temperature` | number | 아니오 | - | `0`에서 `2` 사이의 샘플링 temperature. 값이 높을수록 변형이 추가될 수 있음. |
| `streaming` | boolean | 아니오 | `false` | 문장 단위로 오디오 스트리밍 |

성공한 speech 응답은 바이너리 오디오이며, `Content-Type`이 반환된 형식을 나타냅니다. `response_format`을 생략하면 모델 기본값이 사용됩니다. 재정의하기 전에 `GET /models?type=tts`에서 `model_spec.supported_formats`와 `model_spec.default_format`을 조회하세요. 지원되지 않는 형식을 요청하면 HTTP `400`이 반환됩니다.

## 일반적인 오류

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


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