Supertone APIは3つのステップで迅速に連携してご利用いただけます。

1

認証

Supertone APIは、HTTPリクエストヘッダーを通じたキー認証方式を使用します。API Keyは開発者コンソールページで発行して使用できます。

2

ボイスIDの選択

Get Voices APIを呼び出して、利用可能なボイスを確認してください。Supertone Playでコンテンツを作成しながら様々なボイスを探索して選択することもできます。

3

API呼び出し

選択したボイスIDでテキストを音声に変換するAPIを呼び出すことができます。

1. 認証

すべてのAPIリクエストには認証が必要です。API キーを発行してHTTPヘッダーに含めてリクエストしてください。

API キーの発行

Supertone API キーは、クローズドベータサービス承認後、コンソールページで直接発行できます。

発行ポリシー

  1. アカウントあたり一度に最大3つのAPI キーを発行可能
    • 開発環境別に区分して使用することを推奨します(例:DevStageProduction
  2. いつでもキーの破棄および再発行が可能
    • セキュリティ上の理由でキーの交換が必要な場合
    • キーの漏洩が疑われる場合
    • プロジェクト単位でキーを区分したい場合

発行手順

  1. コンソールページにログイン
  2. サイドバー > API Keysメニューにアクセス
  3. ‘Create API Key’ボタンをクリックしてキー発行完了

API認証

Supertone APIは、HTTPリクエストヘッダーを通じたAPI キー認証方式を使用します。

ヘッダー構成

  • キー:x-sup-api-key
  • 値:発行されたAPI キー
  • Base URL:https://supertoneapi.com

すべてのAPIリクエストには、必ずこの認証ヘッダーを含める必要があります。ヘッダーが欠落しているか、誤ったAPI キーが提供された場合、401 Unauthorizedレスポンスが返されます。

x-sup-api-key: YOUR_API_KEY

認証コード例

各プログラミング言語別の認証実装例です。

curl -X GET "https://supertoneapi.com/v1/voices" \
     -H "x-sup-api-key: YOUR_API_KEY"

注意事項

  • API キーは露出しないよう、環境変数や設定ファイルに別途保管して管理してください。
  • API キーが露出した場合、直ちにコンソールで該当のキーを破棄し、新しいキーを発行してください。
  • すべてのAPI通信はHTTPSを通じて行われるため、SSL/TLS証明書関連の問題がないか確認してください。
  • 401エラーが発生する場合、API キーが正しいか、ヘッダー名が正確かを確認してください。

2. ボイスIDの取得

ご希望の音声を確認するには、Get Voices APIまたはSearch Voices APIを呼び出して直接音声を探索することができます。

Get Voices APIを呼び出して確認

Get Voices APIを呼び出して、利用可能なボイスの一覧を確認できます。APIは以下のような形式のJSON応答を返します。JSON応答に含まれるvoice_idをAPI呼び出し時のパラメータとして入力します。

{
    "voices": [
        {
            "voice_id": "54CyP2zU9HCeLVCpzDRFPi",
            "name": "Yoonho",
            "description": "Yoonho is a sarcastic and indifferent teenager. He doesn't express his emotions well.",
            "age": "young-adult",
            "gender": "male",
            "use_case": "game",
            "language": "ko",
            "style": "blank_high"
        }
    ]
}

Search Voices APIを呼び出して確認

Search Voices APIを呼び出して、様々なキーワードとフィルターを使って音声を検索することができます。 APIは次のような形式のJSON応答を返します。 JSON応答に含まれるvoice_idをAPI呼び出しに活用してください。

{
  "voices": [
    {
      "voice_id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "age": "<string>",
      "gender": "<string>",
      "use_case": "<string>",
      "language": "<string>",
      "style": "<string>"
    }
  ],
  "total": 123,
  "page": 123,
  "page_size": 123,
  "total_pages": 123
}

3. 音声合成(Text-to-speech)

選択したボイスIDでテキストを音声に変換します。

基本リクエスト例

curl -X POST "https://supertoneapi.com/v1/text-to-speech?output_format=wav" \
     -H "x-sup-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "voice_id": "54CyP2zU9HCeLVCpzDRFPi",
           "language": "en",
           "text": "Good morning. Rise and shine!"
         }'

ファイル形式の指定

対応形式

output_formatクエリパラメータでファイル形式を指定できます。

  • wav:?output_format=wav
  • mp3:?output_format=mp3
# WAV形式のリクエスト
https://supertoneapi.com/v1/text-to-speech?output_format=wav

# MP3形式のリクエスト
https://supertoneapi.com/v1/text-to-speech?output_format=mp3