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.
이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문 을 함께 확인해 주세요. 이 빠른 시작 가이드는 인증부터 재생 가능한 오디오 파일까지, 처음 Supertone API를 호출하는 과정을 단계별로 안내합니다.
1. API Key 발급받기 Supertone API는 API Key 기반 인증을 사용합니다. 개발자 콘솔에서 발급받으세요.
console.supertoneapi.com 에서 가입합니다.새 서비스를 생성하고 발급된 키를 복사합니다.
소스 코드에 노출되지 않도록 환경 변수로 저장합니다.
export SUPERTONE_API_KEY = "Kp9mZ3xQ7v..."
계정당 최대 3개의 API Key를 발급받을 수 있습니다. 키가 유출된 경우 콘솔에서 폐기하고 재발급하세요.
2. 첫 음성 생성하기 아래에서 사용할 언어를 선택하고 스니펫을 실행하세요. Python 및 TypeScript SDK는 인증, 재시도, 긴 텍스트의 청크 분할을 기본으로 처리합니다.
코드에는 예시 voice_id가 포함되어 있습니다. 동작을 확인한 뒤에는 보이스 라이브러리 에 있는 원하는 보이스로 교체하세요.
SDK를 설치합니다. pip install supertone # or: uv add supertone # or: poetry add supertone
quickstart.py를 생성합니다.import os from supertone import Supertone VOICE_ID = "20160a4c5ba38967330c84" # example voice — replace with your own with Supertone( api_key =os.environ[ "SUPERTONE_API_KEY" ]) as client: response = client.text_to_speech.create_speech( voice_id =VOICE_ID, text = "Hello from Supertone. This audio was generated with the Python SDK." , language = "en" , output_format = "wav" , ) with open ( "speech.wav" , "wb" ) as f: f.write(response.result.read()) print ( "Saved speech.wav" )
실행합니다. SDK를 설치합니다. npm add @supertone/supertone # or: pnpm add @supertone/supertone # or: bun add @supertone/supertone # or: yarn add @supertone/supertone zod
quickstart.ts를 생성합니다.import { Supertone } from "@supertone/supertone" ; import * as fs from "node:fs" ; const VOICE_ID = "20160a4c5ba38967330c84" ; // example voice — replace with your own const client = new Supertone ({ apiKey: process . env . SUPERTONE_API_KEY }); const response = await client . textToSpeech . createSpeech ({ voiceId: VOICE_ID , apiConvertTextToSpeechUsingCharacterRequest: { text: "Hello from Supertone. This audio was generated with the TypeScript SDK." , language: "en" , outputFormat: "wav" , }, }); if ( response . result instanceof Uint8Array ) { fs . writeFileSync ( "speech.wav" , response . result ); } else if ( response . result && "getReader" in response . result ) { const reader = ( response . result as ReadableStream < Uint8Array >). getReader (); const chunks : Uint8Array [] = []; while ( true ) { const { done , value } = await reader . read (); if ( done ) break ; if ( value ) chunks . push ( value ); } fs . writeFileSync ( "speech.wav" , Buffer . concat ( chunks )); } console . log ( "Saved speech.wav" );
실행합니다. VOICE_ID = "20160a4c5ba38967330c84" # example voice — replace with your own curl -X POST "https://supertoneapi.com/v1/text-to-speech/ $VOICE_ID " \ -H "x-sup-api-key: $SUPERTONE_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "text": "Hello from Supertone. This audio was generated with cURL.", "language": "en", "model": "sona_speech_1" }' \ --output speech.wav
응답 본문은 원시 오디오 파일입니다. X-Audio-Length 응답 헤더로 생성된 음성의 길이(초)를 확인할 수 있습니다. speech.wav를 열어보세요. 예시 보이스로 문장이 발화된 것을 들을 수 있습니다.3. 내부에서 일어나는 일 Step What it does Supertone(api_key=...) / new Supertone({ apiKey })클라이언트를 생성합니다. 키는 x-sup-api-key 헤더로 전송됩니다. voice_id어떤 캐릭터가 텍스트를 발화할지 지정합니다. text합성할 스크립트입니다. API 호출당 최대 300자 까지 가능합니다. SDK는 더 긴 텍스트를 자동으로 청크 분할합니다. language텍스트의 언어입니다. 필수 항목이며, 해당 보이스와 모델이 지원하는 언어여야 합니다. model기본값은 sona_speech_1입니다. 모델별 차이는 모델 을 참고하세요. output_formatwav(기본값) 또는 mp3.
SDK는 타입 안전성을 위해 enum 상수도 제공합니다(예: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.EN). 일반 문자열과 enum 둘 다 사용 가능하니 선호하는 방식을 선택하세요.
4. 다음 단계
더 많은 보이스 찾기 프리셋 보이스 라이브러리를 탐색하고 사용 사례에 맞는 voice_id를 찾으세요.
모델 선택하기 sona_speech_2, sona_speech_2_flash, supertonic_api_3, supertonic_api_1, sona_speech_1 중에서 선택하세요.
긴 텍스트 처리하기 300자 API 제한과 SDK의 자동 청크 분할을 이해하세요.
보이스 튜닝하기 voice_settings로 피치, 억양, 속도를 조정하세요.
