커스텀 보이스

이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.

커스텀 보이스(custom voice) 는 내 계정에 연결된 보이스 클론입니다. 한 번 등록되면 프리셋 보이스와 동일하게 동작합니다 — 같은 TTS 엔드포인트, 같은 파라미터를 사용하지만, 별도의 엔드포인트에 존재하며 해당 보이스를 생성한 계정에서만 호출할 수 있습니다. 커스텀 보이스는 두 가지 방법으로 생성할 수 있습니다.

Supertone Play에서 생성 — 샘플을 업로드하고 UI를 통해 클로닝합니다.
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}`	커스텀 보이스를 영구 삭제합니다.

클론 생성하기

클로닝하려는 보이스의 깨끗한 오디오 샘플을 업로드하세요.

Python
TypeScript
cURL

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초)가 가장 좋은 클로닝 결과를 만듭니다. 배경 음악, 여러 명의 음성, 심한 룸 노이즈는 피하세요.

조회 및 검색

Python
TypeScript
cURL

# 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 레퍼런스

요청과 응답의 전체 스키마를 확인하세요.

비용 및 사용량

비용을 예측하고 보이스별 사용량을 모니터링하세요.

Announcement

엔드포인트 개요

클론 생성하기

업로드 제약사항

조회 및 검색

TTS에서 커스텀 보이스 사용하기

수정 또는 삭제

중요 제약사항

관련 문서

프리셋 보이스

엔드투엔드 예제

API 레퍼런스

비용 및 사용량

​엔드포인트 개요

​클론 생성하기

​업로드 제약사항

​조회 및 검색

​TTS에서 커스텀 보이스 사용하기

​수정 또는 삭제

​중요 제약사항

​관련 문서

프리셋 보이스

엔드투엔드 예제

API 레퍼런스

비용 및 사용량

엔드포인트 개요

클론 생성하기

업로드 제약사항

조회 및 검색

TTS에서 커스텀 보이스 사용하기

수정 또는 삭제

중요 제약사항

관련 문서