> ## Documentation Index
> Fetch the complete documentation index at: https://supertone-b89202c8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 빠르게 시작하기

> SDK를 설치하고, API Key를 설정한 뒤, 5분 안에 첫 음성 오디오를 생성합니다.

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

이 빠른 시작 가이드는 인증부터 재생 가능한 오디오 파일까지, 처음 Supertone API를 호출하는 과정을 단계별로 안내합니다.

## 1. API Key 발급받기

Supertone API는 API Key 기반 인증을 사용합니다. 개발자 콘솔에서 발급받으세요.

1. [console.supertoneapi.com](https://console.supertoneapi.com)에서 가입합니다.
2. 새 서비스를 생성하고 발급된 키를 복사합니다.
3. 소스 코드에 노출되지 않도록 환경 변수로 저장합니다.

```bash theme={"dark"}
export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
```

> [!NOTE]
>
> 계정당 최대 3개의 API Key를 발급받을 수 있습니다. 키가 유출된 경우 콘솔에서 폐기하고 재발급하세요.

## 2. 첫 음성 생성하기

아래에서 사용할 언어를 선택하고 스니펫을 실행하세요. Python 및 TypeScript SDK는 인증, 재시도, 긴 텍스트의 청크 분할을 기본으로 처리합니다.

코드에는 예시 `voice_id`가 포함되어 있습니다. 동작을 확인한 뒤에는 [보이스 라이브러리](/ko/docs/core-concepts/voices)에 있는 원하는 보이스로 교체하세요.

**Python**

SDK를 설치합니다.

```bash theme={"dark"}
pip install supertone
# or: uv add supertone
# or: poetry add supertone
```

`quickstart.py`를 생성합니다.

```python theme={"dark"}
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")
```

실행합니다.

```bash theme={"dark"}
python quickstart.py
```

**TypeScript**

SDK를 설치합니다.

```bash theme={"dark"}
npm add @supertone/supertone
# or: pnpm add @supertone/supertone
# or: bun add @supertone/supertone
# or: yarn add @supertone/supertone zod
```

`quickstart.ts`를 생성합니다.

```typescript theme={"dark"}
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");
```

실행합니다.

```bash theme={"dark"}
npx tsx quickstart.ts
```

**cURL**

```bash theme={"dark"}
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`입니다. 모델별 차이는 [모델](/ko/docs/core-concepts/models)을 참고하세요. |
| `output_format` | `wav`(기본값) 또는 `mp3`. |

SDK는 타입 안전성을 위해 enum 상수도 제공합니다(예: `models.APIConvertTextToSpeechUsingCharacterRequestLanguage.EN`). 일반 문자열과 enum 둘 다 사용 가능하니 선호하는 방식을 선택하세요.

## 4. 다음 단계

> **[더 많은 보이스 찾기](/ko/docs/core-concepts/voices)**
>
> 프리셋 보이스 라이브러리를 탐색하고 사용 사례에 맞는 `voice_id`를 찾으세요.

> **[모델 선택하기](/ko/docs/core-concepts/models)**
>
> `sona_speech_2`, `sona_speech_2_flash`, `supertonic_api_3`, `supertonic_api_1`, `sona_speech_1` 중에서 선택하세요.

> **[긴 텍스트 처리하기](/ko/docs/text-to-speech/long-text)**
>
> 300자 API 제한과 SDK의 자동 청크 분할을 이해하세요.

> **[보이스 튜닝하기](/ko/docs/text-to-speech/voice-settings)**
>
> `voice_settings`로 피치, 억양, 속도를 조정하세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.