音声合成API:開発者向けクイックスタートガイド

作成者 KotobaMenu エディトリアルチーム · 更新日 2026-11-19

KotobaMenuの音声合成APIドキュメントは、飲食店や給食施設のメニュー読み上げ・アナウンス機能をアプリケーションに組み込むための実装ガイドです。このページでは、APIキーの取得から初回のリクエスト送信、OpenAI SDKとの連携方法まで、具体的な手順と数値を交えて解説します。インドゥー開発者が迷わず実装できるよう、必要なパラメータやエラー処理を網羅しています。

既存のOpenAI互換エンドポイントを利用するため、base_urlの変更だけで迅速に統合可能です。モデルの選択、音声プリセット、速度調整、言語設定などの詳細なパラメータ説明と、レートリミットや認証セキュリティの実装ポイントを含みます。実務で必要な数値(文字数制限や料率)を正確に記載し、無駄のない実装を支援します。

音声合成API:開発者向けクイックスタートガイド

よくある質問

APIキーはどのように生成されるか

Googleまたはメールアドレスとパスワードでサインアップすると、ダッシュボードにAPIキーが表示されます。キーは1アカウントあたり1つで、新しいキーを発行すると旧キーは即時無効になります。認証にはAuthorizationヘッダーにBearerトークンとして設定してください。

base_url はどのようになるか

OpenAI SDKを使用する場合、base_urlを「https://api.777300er.info/v1」に変更して利用します。これにより、公式SDKの互換性を利用して音声合成エンドポイントにアクセスできます。リクエスト形状はOpenAIのspeechエンドポイントと同一です。

curl コマンドの例は提供されているか

はい、/get-api-key/ページでcurlコマンドの例が提供されています。ダッシュボードにはキー、残高、使用状況とともに、すぐに実行可能なコマンド例が表示されるため、開発者はすぐにAPI接続テストを行うことができます。

OpenAI SDK のバージョンは問われるか

互換性のある公式OpenAI SDKであれば、base_urlの変更だけで動作します。

エラー時のレスポンスボディはどうか

合成に失敗した場合、請求は全額返金されます。失敗したリクエストに対しては課金が行われません。

レートリミットはキー単位かアカウント単位か

レートリミットはAPIキー単位で適用されます。1分間あたり60リクエストまで可能ですが、初回のチャージ前は1分間あたり10リクエストに制限されます。複数のキーを持つ場合、それぞれに制限が適用されます。

音声の長さが4096文字を超えた場合

4096文字を超えるテキストは、最大4096文字のパートに分割して送信する必要があります。生成された各音声ファイルをクライアント側で結合することで、長いテキストの音声化を実現します。

言語コードは必須か

必須ではありません。指定しない場合、スクリプトに基づいて言語が推測されます(ラテン文字は英語とみなされます)。ただし、英語以外のラテン文字テキストでは、言語コードを明示的に設定することを推奨します。

速度調整はリアルタイムか

速度調整はAPIリクエストのパラメータとして指定します(0.25〜4.0)。生成処理自体はキューイングされることがあり、短くても数秒、長いテキストでは実時間程度の処理時間がかかります。リアルタイムストリーミングではありません。

フォーマットの変更は可能か

可能です。mp3、wav、opus、flac、pcmの5つのフォーマットから選択できます。リクエストボディのresponse_formatフィールドに希望するフォーマットを指定することで、出力形式を変更できます。

APIのエンドポイントは固定か

はい、エンドポイントは固定です。音声合成は「POST https://api.777300er.info/v1/audio/speech」、音声一覧取得は「GET /v1/voices」、モデル情報は「GET /v1/models」でアクセスします。

HTTPS は必須か

APIエンドポイントはHTTPS(https://api.777300er.info/v1)で提供されています。セキュリティのため、API通信にはHTTPSの使用が推奨されます。

JSON 以外のフォーマットは対応するか

リクエストボディはJSON形式のみ対応しています。音声の出力フォーマットはmp3、wav、opus、flac、pcmから選択可能ですが、APIへの入力データ形式はJSONに限定されます。

デバッグログは取得できるか

デバッグログの取得機能は特に記載されていません。リクエストメタデータ(時刻、文字数、ステータス)は課金のために保持されますが、詳細なデバッグログをAPI側で取得する機能は提供されていません。

最初のリクエスト

curl

curl https://api.777300er.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.777300er.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.777300er.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
aria女性
nova女性
luna女性
sage女性
felix男性
milo男性
atlas男性
orion男性
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

APIキーの取得

の音声波形イラスト: APIキーの取得

KotobaMenuの音声合成APIを利用するには、まずAPIキーの取得が必要です。独立したストアフロントとして、サイトごとにアカウントが管理されます。

初期設定は数分で完了し、ダッシュボードからすぐにAPIの使用を開始できます。

Googleサインインでの登録

Googleサインインでの登録

Googleアカウントを使用して簡単に登録できます。この方法では、即時に0.50ドルのトライアルクレジット(約5万文字分)が付与されます。有効期限は7日間です。

メールアドレスとパスワードでの登録とは異なり、トライアルクレジットの有無が初期コストの計画に影響します。

  • Googleアカウントでのワンクリック登録
  • トライアルクレジット(0.50ドル)が自動付与
  • 有効期限:登録から7日間

メールアドレスでの登録

メールアドレスでの登録

メールアドレスとパスワードを使ってアカウントを作成することも可能です。この方法で登録した場合、トライアルクレジットは付与されません。

本格的な利用を開始する前に、USDT(TRC-20)でのチャージが必要です。

アカウントはサイトごとに独立して管理されます。

  • メールアドレスとパスワードでの登録
  • トライアルクレジットなし
  • チャージ後のみ利用可能

ダッシュボードでの確認

登録完了後、/get-api-key/ページでAPIキーと残高を確認できます。ここでは、発行済みのキー、残高、トライアルの状態、および使用可能な文字数が表示されます。

また、すぐに試せるcurlコマンドの例も記載されているので、すぐに開発を始めてください。

キーは1アカウントにつき1つ有効で、新しいキーを発行すると古いキーは即時無効になります。

  • APIキーと残高の確認
  • curlコマンド例の確認
  • キーの再発行機能

最初のリクエスト(curl)

の音声波形イラスト: 最初のリクエスト(curl)

音声合成APIは、テキストを送信して音声ファイルを受け取るシンプルなPOSTエンドポイントです。以下は、curlコマンドで「tts-1」モデルを使用して音声を作成する基本的なリクエスト例です。

JSONボディには、生成対象のテキスト、使用する音声のプリセット、出力形式を指定します。成功すると、音声データがレスポンスボディに返されます。

基本的なPOSTリクエスト

エンドポイントは POST https://api.777300er.info/v1/audio/speech です。認証ヘッダーにAPIキーを設定し、JSON形式でリクエストボディを送信します。

curl コマンドの例: ```bash curl -X POST https://api.777300er.info/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "本日のスペシャルはカレーライスです", "voice": "nova", "response_format": "mp3"}' ```

JSONボディの構成

必須パラメータは model("tts-1" または "tts-1-hd"), input(最大4096文字のテキスト), voice(8つのプリセットから選択), response_format(mp3, wav, opus, flac, pcm)です。, speed は0.25〜4.0の範囲で調整可能です。

メニュー読み上げでは、input に読み上げたい文字列をそのまま設定します。文字数にスペースや句点も含まれるため、正確なカウントが必要です。

  • model: "tts-1" または "tts-1-hd"
  • input: 最大4096文字のテキスト
  • voice: aria, nova, luna, sage, felix, milo, atlas, orion
  • response_format: mp3, wav, opus, flac, pcm

レスポンスの受信

リクエストが成功すると、音声ファイル(mp3など)がレスポンスボディとして返されます。ステータスコードは200です。

音声合成に失敗した場合は、エラーコードと詳細メッセージが返され、課金は行われません。ネットワークエラーやレートリミット超過時は、適切なエラーハンドリングを実装してください。

OpenAI SDKとの連携

の音声波形イラスト: OpenAI SDKとの連携

KotobaMenuの音声合成APIは、OpenAIのspeechエンドポイントと完全に互換性があります。base_urlをhttps://api.777300er.info/v1に変更するだけで、既存の公式SDKをそのまま利用できます。

認証にはAuthorization: Bearer <your_key>ヘッダーを設定します。この仕組みにより、特別なライブラリ追加なしで、飲食店向けの音声案内アプリを効率的に構築できます。

base_urlの変更

SDKの初期化時に、APIベースURLをhttps://api.777300er.info/v1に設定してください。これにより、すべてのリクエストがKotobaMenuの音声合成エンジンにルーティングされます。

同じリクエスト形状

JSONボディの構造はOpenAIのspeechエンドポイントと同じです。model、input、voice、response_formatなどのフィールド名を変更する必要はありません。

  • model: "tts-1" または "tts-1-hd"
  • input: 合成対象のテキスト(最大4096文字)
  • voice: 8種類のプリセットから選択
  • response_format: mp3, wav, opus, flac, pcm

公式SDKの互換性

Python、Node.js、Goなどの公式OpenAI SDKは、base_urlの変更だけで動作します。認証ヘッダーとエンドポイントURLのみ調整してください。

パラメータの詳細

の音声波形イラスト: パラメータの詳細

音声合成APIのパラメータは、生成される音声の品質と形式を制御します。OpenAI互換のシンプルなJSON形式で指定でき、開発者は直感的に音声コンテンツを調整できます。

各パラメータは、飲食店や給食施設の音声コンテンツ制作において、メニュー読み上げやアナウンスの品質を最適化するために設計されています。

model の選択

APIはtts-1とtts-1-hdの2つのモデルを提供します。これらは同一のエンジンを使用しており、料金は同一です(100万文字あたり10ドル)。tts-1-hdを選択しても、より高いコストは発生しません。

voice のプリセット

8種類の音声プリセットから選べます。ariaは温かみのあるナレーター、novaは明るく活気のある音声、lunaは柔らかく物語的なトーンです。sageは落ち着いた教育系、felixはエネルギッシュなプロモーション向け、miloは親しみやすい会話型です。atlasはニュートラルなニュース向け、orionは深みのあるドキュメンタリー向けです。

すべての音声は23言語に対応しており、日本語のメニュー読み上げにも適しています。音声はLibriTTS-RとLibriVoxのライセンスに基づいています。

  • aria, nova, luna, sage, felix, milo, atlas, orion

response_format の指定

音声ファイルの出力形式は、mp3、wav、opus、flac、pcmから選択できます。mp3は軽量でWeb配信に適し、wavは高音質な保存用です。opusは帯域幅を抑えつつ高品質を保ちます。

リクエストごとに形式を指定でき、必要に応じてファイルサイズと音質のバランスを取れます。生成された音声には合成音声を示す不可視の透かしが含まれます。

速度と言語の設定

の音声波形イラスト: 速度と言語の設定

音声合成APIでは、speedパラメータを使用して生成速度を調整できます。範囲は0.25から4.0で、標準は1.0です。短縮すると語速が上がり、延長するとゆっくりとした読み上げになります。

言語指定はISOコードで実施します。指定しない場合はスクリプトから自動判定されますが、英語以外のラテン文字テキストでは明示的にlanguageを設定することをお勧めします。

speed の範囲

速度パラメータは0.25(約1/4速)から4.0(4倍速)まで指定可能です。デフォルトは1.0で、通常の会話速度に相当します。メニュー読み上げでは可読性を保つため、標準またはやや遅めの設定が推奨されます。

  • 最小: 0.25
  • 最大: 4.0
  • デフォルト: 1.0

language のISOコード

対応言語は23種類です。英語、日本語、中国語、韓国語、フランス語、ドイツ語、スペイン語、イタリア語、ポルトガル語、ロシア語、アラビア語、ヒンディー語、タイ語以外の東南アジア言語などをサポートしています。

音声は言語に依存せず8種類のボイスから選択可能ですが、適切な言語コードを設定することで、発音の精度が向上します。

自動言語検出

言語フィールドが未設定の場合、入力テキストのスクリプト(文字種)に基づいて言語が自動推定されます。ラテン文字のテキストはデフォルトで英語として扱われるため、日本語や中国語のラテン文字表記(ローマ字など)を使用する場合は明示的な指定が必要です。

誤った自動検出を防ぐため、多言語混在のメニューやアナウンスでは、主要言語のISOコードを明示してください。

速度と言語の設定

エラー処理とステータス

の音声波形イラスト: エラー処理とステータス

API呼び出しが失敗した場合、生成は行われず請求も発生しません。エラーレスポンスを受け取った際は、ステータスコードとエラーメッセージを確認し、原因を特定してください。

一時的なネットワーク障害やサーバー側の処理遅延は、リトライ処理で対応可能です。失敗したリクエストに対する課金は全額返金されます。

一般的なエラーコード

400エラーはリクエスト形式の誤り、401はAPIキーの有効期限切れや無効なキーを示します。422エラーは、音声やフォーマットの不整合など、パラメータの検証失敗時に返されます。

  • 400: Invalid request format
  • 401: Invalid authentication
  • 422: Unprocessable entity

レートリミット超過

APIキーごとに1分間あたり60リクエストの制限があります。トップアップ前は1分間あたり10リクエストです。制限超過時は429エラーが発生します。

  • 通常: 60 req/min
  • 初回: 10 req/min
  • リトライ: 429エラー後

タイムアウトの処理

サーバーの負荷が高い場合、リクエストがキューイングされ応答に時間がかかることがあります。タイムアウト時は、同じリクエストを再送信してください。重複課金は避けられます。

レートリミットの実装

の音声波形イラスト: レートリミットの実装

KotobaMenuのAPIレートリミットは、APIキーあたり1分間あたり60リクエストです。初回トップアップ前は1分間あたり10リクエストに制限されます。これは同時実行数ではなく、時間窓内のリクエスト総数に基づいて評価されます。

1分間あたり60リクエスト

各APIキーは1分間に最大60件のリクエストを処理できます。これは、レストランメニューの読み上げや給食施設のアナウンス配信など、バッチ処理に適した制限です。

キューイングの仕組み

リクエストは順番に処理されます。負荷が高い場合、リクエストはキューに待機状態になります。これにより、音声合成エンジンの安定性が保たれます。

負荷時の遅延対策

長時間のテキストでは、4096文字ごとに分割して生成されます。リクエストがキューに待機している場合、音声合成に通常より時間がかかる可能性があります。タイムアウト時は、同じリクエストを再送信してください。

認証とセキュリティ

の音声波形イラスト: 認証とセキュリティ

認証には Authorization: Bearer tts-... ヘッダーを使用します。1アカウントにつき有効なキーは1つのみで、セキュリティを簡素化しています。

Bearer トークンの使用

APIリクエストのヘッダーに Authorization: Bearer {YOUR_API_KEY} を設定してください。これにより、KotobaMenu API はリクエスト元のアカウントを識別し、適切な課金とレート制限を適用します。

APIキーの管理

ダッシュボードで現在有効なキーを確認できます。キーはアカウントごとに一意であり、セキュリティのため常に最新のキーを使用することを推奨します。

  • ダッシュボードで現在のキーを表示
  • キーは1つのみ有効

キーの再発行

ダッシュボードから新しいキーを発行すると、古いキーは即座に無効になります。これにより、万が一キーが漏洩した場合でも、即座にアクセスを遮断できます。

再発行は安全対策として頻繁に行うことをお勧めします。

8つの音声を確認

以下の各サンプルは、同じ文章をこのAPIで生成したものです。 飲食店や給食施設での利用を想定し、メニュー読み上げやアナウンス機能に求められる「確実な伝達」と「組み込みの容易さ」を最優先基準とします。

音声のアバター aria
aria女性
音声のアバター nova
nova女性
音声のアバター luna
luna女性
音声のアバター sage
sage女性
音声のアバター felix
felix男性
音声のアバター milo
milo男性
音声のアバター atlas
atlas男性
音声のアバター orion
orion男性

23言語

どの音声でも、これらの言語のいずれかを話します。

出典および参考資料

  1. Wikipedia
  2. MDN: Web Speech API
  3. Tether (USDT)
  4. ISO 639 language codes
  5. OpenAI API reference: create speech
  6. FFmpeg documentation
  7. openai-python on GitHub
  8. openai-node on GitHub
  9. IETF RFC 7845: Ogg Opus
  10. W3C WAI: making audio and video accessible
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. Creative Commons Attribution 4.0

このサイトに関するその他の情報