> ## 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]
>
> 1つのアカウントにつき最大3つのAPI Keyを発行できます。キーが流出した場合は、コンソールから廃棄して再発行してください。

## 2. 最初の音声を生成する

下記のタブから言語を選択し、スニペットを実行してください。PythonおよびTypeScript SDKは、認証、リトライ、長文の自動チャンク分割を標準でサポートしています。

サンプルコードでは例示用の`voice_id`を使用しています。動作を確認したら、[ボイスライブラリ](/ja/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. 内部で起きていること

| ステップ | 内容 |
| - | - |
| `Supertone(api_key=...)` / `new Supertone({ apiKey })` | クライアントを生成します。API Keyは`x-sup-api-key`ヘッダーに送信されます。 |
| `voice_id` | どのキャラクターがテキストを発話するかを指定します。 |
| `text` | 合成するスクリプト。API呼び出し1回あたり最大**300文字**です。SDKは長文を自動でチャンク分割します。 |
| `language` | テキストの言語。必須項目で、ボイスとモデルの両方が対応している必要があります。 |
| `model` | デフォルトは`sona_speech_1`です。トレードオフについては[モデル](/ja/docs/core-concepts/models)を参照してください。 |
| `output_format` | `wav`（デフォルト）または`mp3`。 |

SDKは型付きのenum定数（例：`models.APIConvertTextToSpeechUsingCharacterRequestLanguage.EN`）も提供しています。プレーンな文字列より型安全性を重視する場合に使用できます。どちらのスタイルでも動作します。

## 4. 次のステップ

> **[さらに多くのボイスを探す](/ja/docs/core-concepts/voices)**
>
> プリセットライブラリを閲覧し、用途に合った`voice_id`を見つけましょう。

> **[モデルを選ぶ](/ja/docs/core-concepts/models)**
>
> `sona_speech_2`、`sona_speech_2_flash`、`supertonic_api_3`、`supertonic_api_1`、`sona_speech_1`から選択できます。

> **[長文を扱う](/ja/docs/text-to-speech/long-text)**
>
> APIの300文字制限とSDKの自動チャンク分割を理解しましょう。

> **[ボイスを調整する](/ja/docs/text-to-speech/voice-settings)**
>
> `voice_settings`でピッチ、イントネーション、スピードを調整します。


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