메인 콘텐츠로 건너뛰기
보이스 체인저는 speech-to-speech입니다. 녹음을 전달하고 음성을 지정하면, 같은 연기를 그 음성으로 돌려받습니다. 단어, 쉼, 강세, 길이가 모두 그대로입니다. 이미 살리고 싶은 테이크가 있을 때 사용하는 기능입니다. 텍스트만 있다면 text-to-speech를 사용하고, 자신의 목소리를 대상 음성으로 쓰고 싶다면 보이스 클로닝을 참고하세요. 다음은 /audio/speech로 만든 7초 클립과 이를 George 음성으로 변환한 결과입니다. 두 파형은 같은 시간축 위에 있으며, 구절 사이의 공백이 같은 위치에 놓입니다.
같은 시간축에 위아래로 놓인 두 파형: 파란색은 원본 녹음, 주황색은 변환된 녹음이며 무음 구간이 일치함
변환은 /audio/voice-changer/ 아래의 네 엔드포인트를 통해 비동기로 실행됩니다. quote는 길이에 대한 가격을 산정하고, queue는 녹음을 제출하고 요금을 청구하며, retrieve는 MP3가 준비될 때까지 폴링하고, complete는 결과를 받은 뒤 저장된 미디어를 삭제합니다. 구조는 음악 엔드포인트와 같지만 경로가 다르며, 서로의 모델을 허용하지 않습니다. 예제는 VENICE_API_KEY가 설정되어 있다고 가정합니다:

모델 선택

보이스 체인저 모델은 GET /models?type=music 아래에 있으며 model_spec.voice_changer가 true로 설정되어 있습니다. 전용 타입 필터는 없습니다. 현재는 elevenlabs-voice-changer 하나뿐입니다. 이 모델은 최대 300초 길이의 mp3, wav, ogg, mp4, aac 원본을 받으며, Aria를 기본값으로 하는 20개의 이름 있는 음성을 제공하고, 이름 대신 ElevenLabs Voice ID를 그대로 받을 수 있으며, remove_background_noise와 seed를 지원합니다. 이러한 세부 사항은 바뀔 수 있으므로 API에서 읽어 오세요. 다음 쿼리는 이 가이드의 나머지 부분에 필요한 모든 정보를 반환합니다:
모델이 지원하지 않는 필드를 보내면 400이 반환됩니다. max_source_audio_duration_seconds보다 긴 녹음은 요금이 청구되기 전에 422를 반환하며, 메시지에 최대값이 표시됩니다. API가 큐 등록 시점에 확인하지 않는 것이 하나 있는데, 바로 음성 이름입니다. 모델에 없는 voice로 큐에 등록해도 200과 queue_id를 받습니다. 거부는 첫 번째 retrieve에서 도착하며 요금은 환불됩니다. 돈은 돌려받지만 왕복 시간은 낭비되므로, 큐에 등록하기 전에 voices를 확인하세요.

1. 가격 견적 받기

요금은 원본 녹음의 길이를 다음 정수 분으로 올림해 청구됩니다. elevenlabs-voice-changer의 경우 60초까지는 $0.35, 120초까지는 $0.69, 180초까지는 $1.04, 240초까지는 $1.38, 300초까지는 $1.73입니다. 7초 클립은 60초 클립과 같은 비용이 들고, 60.5초는 2분으로 청구됩니다. 짧은 세그먼트가 많다면 각각 따로 큐에 등록하지 말고, 분 경계를 넘지 않는 하나의 파일로 합치세요. 가격 등급은 /models의 pricing.durations에서 가져옵니다. quote는 정수 초 단위 값을 받으며 API 키가 필요하지 않습니다:
이 값은 추정치입니다. 실제 청구 금액은 녹음이 큐에 등록될 때 Venice가 측정하는 길이로 계산됩니다.

2. 변환 큐에 넣기

녹음은 multipart file 업로드 또는 JSON 본문의 audio_url 중 하나로 보내세요. 둘 다 보낼 수는 없습니다. URL은 헤더나 쿠키 없이 공개적으로 접근 가능해야 합니다. Venice가 바이트를 직접 가져오며, URL을 공급자에게 절대 전달하지 않습니다. Venice는 확장자가 아니라 바이트를 검사하므로, 파일은 실제로 허용되는 컨테이너 중 하나여야 하며 비디오 트랙이 포함된 파일은 거부됩니다. curl -F를 사용할 때는 curl이 multipart boundary를 설정할 수 있도록 Content-Type을 직접 지정하지 말고, remove_background_noise는 true/false로, seed는 숫자로 보내세요.
위의 multipart 요청이 페이지 상단의 George 클립을 만든 요청입니다. voice를 생략하면 default_voice가 사용됩니다. supports_custom_voice_id가 true이면 voice에 공급자 Voice ID도 사용할 수 있습니다. elevenlabs-voice-changer의 경우 Venice의 voices 목록에 없는 라이브러리 음성을 포함해, 접근 권한이 있는 모든 ElevenLabs 음성을 의미합니다. remove_background_noise와 seed는 모델이 지원한다고 표시하는 경우에만 허용됩니다. 응답에는 이후 모든 단계에 필요한 핸들이 포함됩니다:
duration_seconds는 Venice가 측정한 길이이며, 청구의 기준이 된 등급입니다. 60으로 견적을 받았는데 여기에 61.2가 표시된다면 2분 요금을 지불한 것입니다. model과 queue_id를 보관하세요. retrieve와 complete 모두에 필요하며, ID는 24시간 동안 유효합니다. 요금은 오디오가 돌아올 때가 아니라 이 시점에 청구되므로, 큐 요청을 재시도하지 마세요. queue_id가 있다면 그 값으로 폴링하세요. 응답을 받지 못했는데 녹음을 다시 보내면 요금이 두 번 청구될 수 있습니다. queue는 분당 40회, retrieve는 분당 120회로 제한되며, 둘 다 x-ratelimit-remaining-requests를 반환합니다.

3. 폴링 및 다운로드

큐 응답에서 받은 값으로 retrieve를 호출하세요:
응답은 둘 중 하나입니다. 작업이 실행 중인 동안에는 JSON을 받습니다:
작업이 끝나면 audio/mpeg를 받으며, 본문이 MP3입니다. Content-Type에 따라 분기하세요. 두 숫자는 밀리초 단위로, 각각 이 모델의 작업이 보통 걸리는 시간과 내 작업이 실행된 시간입니다. 두 값의 차이는 첫 대기 시간으로 적당하지만, 평균은 참고용일 뿐입니다. 148초짜리 원본은 평균 7초에 대해 24초가 걸렸으므로, 긴 입력에서는 execution_duration이 average_execution_time을 넘어서게 됩니다. 그런 경우 몇 초 간격의 고정 주기로 전환해 계속 폴링하세요. 짧은 클립은 반대입니다. 7초 예제는 첫 번째 폴링에서 바로 결과가 돌아왔습니다. 완료된 응답에는 x-venice-audio-duration(초), x-venice-inference-time, x-venice-audio-format, x-venice-model-id, x-venice-model-name이 포함됩니다. 출력은 입력과 관계없이 항상 44.1 kHz, 128 kbps 모노 MP3입니다. 오디오 길이는 원본과 몇 밀리초 이내로 일치해야 합니다. 그보다 많이 차이 난다면 배포하기 전에 직접 들어 보세요.

실패한 경우

공급자가 수락한 뒤 실패한 작업은 본문에 error와 credits_refunded가 포함된 오류 상태로 돌아옵니다. true는 요금이 환불되었다는 뜻입니다. false이면서 메시지가 “please contact support”로 끝난다면 환불 자체가 실패한 것이며, 다음 폴링에서 다시 시도합니다. 결과는 저장되므로 다시 폴링하면 같은 결과가 반복됩니다. 공급자에 도달하지 못한 작업은 다르게 보입니다. retrieve가 최대 10분 동안 계속 PROCESSING을 반환한 뒤 504를 반환하고 환불하므로, PROCESSING 상태의 작업은 최소 그 정도 기다린 후에 멈춘 것으로 판단하세요. 전체 최종 결과 목록은 retrieve 레퍼런스에 있습니다.

정리

retrieve에 delete_media_on_completion: true를 전달하면 오디오를 반환하는 같은 호출에서 저장된 미디어가 삭제됩니다. 이후 해당 ID로 retrieve를 호출하면 404가 반환됩니다. 여러 번 다운로드하려면 이 옵션을 빼고, 작업이 끝났을 때 complete를 호출하세요. complete는 {"success": true}를 반환하며 여러 번 호출해도 안전합니다.

전체 예시

위의 모든 과정을 처음부터 끝까지 수행합니다. 음성이 존재하는지 확인하고, 견적을 받고, 업로드하고, 오디오가 도착할 때까지 폴링한 다음 저장합니다. 제한 시간을 12분으로 둔 이유는 디스패치 실패가 타임아웃이 아니라 환불로 나타나게 하기 위해서입니다.
retrieve가 결과를 반환하면서 미디어를 삭제하므로 complete 호출은 없습니다. 파일이 두 번 이상 필요하다면 delete_media_on_completion을 빼고 complete를 직접 호출하세요.

API 파라미터

Queue

Retrieve 및 complete

오류

관련 리소스