> ## 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分以内に最初の音声を生成しましょう。
このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は[英語の原文](/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..."
```
1つのアカウントにつき最大3つのAPI Keyを発行できます。キーが流出した場合は、コンソールから廃棄して再発行してください。
## 2. 最初の音声を生成する
下記のタブから言語を選択し、スニペットを実行してください。PythonおよびTypeScript SDKは、認証、リトライ、長文の自動チャンク分割を標準でサポートしています。
サンプルコードでは例示用の`voice_id`を使用しています。動作を確認したら、[ボイスライブラリ](/ja/docs/core-concepts/voices)の任意のボイスに差し替えてください。
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
```
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).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
```
```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. 次のステップ
プリセットライブラリを閲覧し、用途に合った`voice_id`を見つけましょう。
`sona_speech_2`、`sona_speech_2_flash`、`supertonic_api_3`、`supertonic_api_1`、`sona_speech_1`から選択できます。
APIの300文字制限とSDKの自動チャンク分割を理解しましょう。
`voice_settings`でピッチ、イントネーション、スピードを調整します。