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.
이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문 을 함께 확인해 주세요. 커스텀 보이스(custom voice) 는 내 계정에 연결된 보이스 클론입니다. 한 번 등록되면 프리셋 보이스와 동일하게 동작합니다 — 같은 TTS 엔드포인트, 같은 파라미터를 사용하지만, 별도의 엔드포인트에 존재하며 해당 보이스를 생성한 계정에서만 호출할 수 있습니다.커스텀 보이스는 두 가지 방법으로 생성할 수 있습니다.
Supertone Play 에서 생성API로 생성 — 오디오 파일과 함께 POST /v1/custom-voices/cloned-voice를 호출합니다.
두 방법 모두 동일한 종류의 보이스를 생성합니다. Play에서 클로닝한 보이스는 list_custom_voices에 나타나고, API로 클로닝한 보이스는 Play에 나타납니다. 별도의 동기화 단계는 없습니다.
API를 통한 보이스 클로닝은 Free 등급에서 지원되지 않습니다. Play에서의 클로닝은 모든 유료 등급에서 사용 가능합니다.
엔드포인트 개요 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}커스텀 보이스를 영구 삭제합니다.
클론 생성하기 클로닝하려는 보이스의 깨끗한 오디오 샘플을 업로드하세요.
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)
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 );
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."
응답에는 새 voice_id가 포함됩니다. TTS 호출에 전달할 값이므로 저장해 두세요.
업로드 제약사항
포맷: WAV 또는 MP3크기: 3 MB 미만이름: 최대 100자
깨끗하고 단일 화자인 모노 오디오(5–30초)가 가장 좋은 클로닝 결과를 만듭니다. 배경 음악, 여러 명의 음성, 심한 룸 노이즈는 피하세요.
조회 및 검색 # 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" )
// 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" });
# 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 "
TTS에서 커스텀 보이스 사용하기 클론이 등록되면, 프리셋 보이스와 동일하게 text_to_speech.create_speech를 호출하면 됩니다. 커스텀 voice_id만 전달하세요.
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 필드를 지원합니다.
수정 또는 삭제 # 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)
// 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 생성 음성과 최종 사용자 고지에 관한 본인 관할 지역의 규정을 확인하세요.
관련 문서
프리셋 보이스 Supertone의 프리셋 보이스 라이브러리를 탐색하고 검색하세요.
엔드투엔드 예제 커스텀 보이스를 클로닝, 조회하고 TTS에서 사용하는 예제입니다.
API 레퍼런스 요청과 응답의 전체 스키마를 확인하세요.
비용 및 사용량 비용을 예측하고 보이스별 사용량을 모니터링하세요.
