クイックスタート - Supertone API Documentation

このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は英語の原文もあわせてご確認ください。

このクイックスタートでは、認証から再生可能なオーディオファイル生成まで、Supertone APIの最初の呼び出しをステップバイステップでご案内します。

1. API Keyを取得する

Supertone APIはAPI Keyベースの認証を使用します。開発者コンソールから発行してください。

console.supertoneapi.comで登録します。
新しいサービスを作成し、生成されたキーをコピーします。
ソースコード管理に含めないよう、環境変数として保存します。

export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."

1つのアカウントにつき最大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. 内部で起きていること

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

​1. API Keyを取得する

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

​3. 内部で起きていること

​4. 次のステップ

さらに多くのボイスを探す

モデルを選ぶ

長文を扱う

ボイスを調整する

1. API Keyを取得する

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

3. 内部で起きていること

4. 次のステップ