빠르게 시작하기 - Supertone API Documentation

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

이 빠른 시작 가이드는 인증부터 재생 가능한 오디오 파일까지, 처음 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가 포함되어 있습니다. 동작을 확인한 뒤에는 보이스 라이브러리에 있는 원하는 보이스로 교체하세요.

Python
TypeScript
cURL

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")

실행합니다.

python quickstart.py

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");

실행합니다.

npx tsx quickstart.ts

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_format`	`wav`(기본값) 또는 `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로 피치, 억양, 속도를 조정하세요.

​1. API Key 발급받기

​2. 첫 음성 생성하기

​3. 내부에서 일어나는 일

​4. 다음 단계

더 많은 보이스 찾기

모델 선택하기

긴 텍스트 처리하기

보이스 튜닝하기

1. API Key 발급받기

2. 첫 음성 생성하기

3. 내부에서 일어나는 일

4. 다음 단계