음성 클로닝을 사용하면 짧은 참조 오디오 샘플에서 제공되는 음성으로 발화를 생성할 수 있습니다. tts-chatterbox-hd를 사용하면 샘플을 /audio/voices에 업로드하고, 반환된 vv_... voice handle을 저장한 다음, 그 handle을 /audio/speech에 전달합니다.
Voice handle은 모델별로 구분됩니다. tts-chatterbox-hd로 생성된 handle은 반드시 tts-chatterbox-hd와 함께 사용해야 합니다.
동작 방식
- 업로드 — 깨끗한 참조 오디오 파일을
POST /audio/voices로 전송합니다
- 저장 — 반환된
id voice handle을 저장합니다
- 생성 —
POST /audio/speech에서 handle을 voice로 전송합니다
사전 준비 사항
- Venice API 키
- MP3, WAV, FLAC 또는 M4A 포맷의 깨끗한 참조 샘플
- 한 명의 화자가 명확하게 말하는 최소 5~10초 분량의 오디오
API 키를 설정하세요:
export VENICE_API_KEY="your-api-key"
1단계: 음성 샘플 업로드
참조 오디오를 multipart form data로 업로드하여 voice handle을 생성합니다:
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"
{
"id": "vv_voice_abc123xyz",
"model": "tts-chatterbox-hd"
}
id를 저장하세요:
export VENICE_VOICE_ID="vv_voice_abc123xyz"
2단계: 음성 생성
클로닝된 voice handle을 speech 요청의 voice로 전달합니다:
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에 기록합니다:
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 모델을 조회하세요:
curl "https://api.venice.ai/api/v1/models?type=tts" \
-H "Authorization: Bearer $VENICE_API_KEY"
tts-chatterbox-hd는 다음과 같이 표시됩니다:
{
"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 | 속도 제한 초과 | 속도 제한 윈도가 리셋된 후 다시 시도하세요. |
