> ## 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.

# 빠르게 시작하기

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

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

이 빠른 시작 가이드는 인증부터 재생 가능한 오디오 파일까지, 처음 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를 발급받을 수 있습니다. 키가 유출된 경우 콘솔에서 폐기하고 재발급하세요.
</Note>

## 2. 첫 음성 생성하기

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

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

<Tabs>
  <Tab title="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
    ```
  </Tab>

  <Tab title="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
    ```
  </Tab>

  <Tab title="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` 응답 헤더로 생성된 음성의 길이(초)를 확인할 수 있습니다.
  </Tab>
</Tabs>

`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. 다음 단계

<CardGroup cols={2}>
  <Card title="더 많은 보이스 찾기" icon="users" href="/ko/docs/core-concepts/voices">
    프리셋 보이스 라이브러리를 탐색하고 사용 사례에 맞는 `voice_id`를 찾으세요.
  </Card>

  <Card title="모델 선택하기" icon="layer-group" href="/ko/docs/core-concepts/models">
    `sona_speech_2`, `sona_speech_2_flash`, `supertonic_api_3`, `supertonic_api_1`, `sona_speech_1` 중에서 선택하세요.
  </Card>

  <Card title="긴 텍스트 처리하기" icon="align-left" href="/ko/docs/text-to-speech/long-text">
    300자 API 제한과 SDK의 자동 청크 분할을 이해하세요.
  </Card>

  <Card title="보이스 튜닝하기" icon="sliders" href="/ko/docs/text-to-speech/voice-settings">
    `voice_settings`로 피치, 억양, 속도를 조정하세요.
  </Card>
</CardGroup>