音声合成API:実装から利用までの完全ガイド

作成者 VoiceLearn API編集部 · 更新日 2026-11-18

このページでは、VoiceLearn APIを用いた音声合成の実装手順を具体的に解説します。APIキーの取得からcurlコマンドによる初回リクエスト、OpenAI SDKとの連携方法まで、ノーコードユーザーでも学習コンテンツや動画の制作効率を向上させるための実用的な情報を提供します。

リクエストパラメータの設定方法、対応フォーマット、レートリミットの扱い方、そして言語指定の注意点まで網羅的に説明します。既存のワークフローにAPIを組み込む際の実装例を基に、安定した音声生成を実現するための技術的ガイドラインをご確認いただけます。

音声合成API:実装から利用までの完全ガイド

よくある質問

APIキーはどのように取得しますか?

https://playbt678.com/get-api-key/ でGoogleまたはメールアドレスとパスワードでサインアップしてください。アカウント作成後、ダッシュボードでAPIキーを確認できます。キーは1アカウントにつき1つ有効で、新しいキーを発行すると古いキーは即時無効になります。

OpenAI SDKはそのまま使えますか?

はい、base_urlを変更すればOpenAI SDKが利用可能です。base_urlを https://api.playbt678.com/v1 に変更し、APIキーを設定するだけで動作します。リクエスト形状はOpenAIのspeechエンドポイントと同じため、既存のSDKコードをそのまま流用して音声合成を実装できます。

base_urlの変更場所は?

SDK初期化時にbase_urlパラメータを https://api.playbt678.com/v1 に設定します。これにより、通常のOpenAIエンドポイントの代わりに当社のAPIが呼び出されます。認証情報はAuthorizationヘッダーにBearer トークンとして付与してください。

音声ファイルの形式は選べますか?

mp3、wav、opus、flac、pcmの5形式から選択可能です。response_formatパラメータで指定します。用途に応じて適切な形式を選定でき、各形式で音声品質やファイルサイズを制御できます。

レートリミットを超えるとどうなりますか?

1分あたり60リクエスト(初回トップアップ前は1分あたり10リクエスト)の制限があります。制限を超えるとリクエストが拒否され、課金されません。キューイングにより待機する可能性があります。

エラーが発生した時の処理方法は?

合成エラーが発生した場合、料金は全額返金されます。課金されないので、エラーレスポンスを確認して再試行または処理を継続してください。正常な生成時のみ課金が発生します。

音声の速度は変更できますか?

speedパラメータで0.25から4.0の範囲で速度を変更できます。デフォルトは1.0です。学習教材の再生速度を調整して、聴取者の理解度に合わせて最適化できます。

言語を指定しない場合どうなりますか?

言語コードが未指定の場合、文字種から言語が推測されます。ラテン文字のテキストはデフォルトで英語として扱われます。日本語や中国語などでは明示的にlanguageパラメータでISOコードを指定してください。

最初のリクエスト

curl

curl https://api.playbt678.com/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.playbt678.com/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.playbt678.com/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キーの取得

VoiceLearn APIの活用を開始するには、まずAPIキーの取得が必要です。登録はサイト内の「/get-api-key/」ページから行い、Googleアカウントまたはメールアドレスの2つの方法から選択できます。

Googleサインインでの登録

Googleサインインでの登録

Googleアカウントでサインインすると、0.50ドルのトライアルクレジットが付与されます。このクレジットは約5万文字分に相当し、7日間有効です。

メールアドレスでの登録

メールアドレスでの登録

メールアドレスとパスワードで登録した場合、トライアルクレジットは付与されません。代わりに、USDT(TRC-20)でのチャージにより残高を追加して利用を開始します。

APIキーの発行と管理

ダッシュボードではキーの表示、残高、使用状況を確認できます。新しいキーを発行すると、以前のキーは即時無効になります。

キーは「Bearer tts-...」の形式で認証に使用し、1アカウントあたり1つのアクティブキーを維持します。

最初のリクエスト:curlコマンド

の音声波形イラスト: 最初のリクエスト:curlコマンド

APIキーの取得後、curlコマンドで最初の音声合成リクエストを送信できます。このAPIはOpenAIのspeechエンドポイントとリクエスト形状が同じです、POSTメソッドでJSONボディを送信するだけで音声ファイルを生成します。

基本的なPOSTリクエスト

以下のように、https://api.playbt678.com/v1/audio/speechへPOSTリクエストを送信します。リクエストボディにはモデル名、音声プリセット、変換対象のテキストを含めます。Authorizationヘッダーには発行されたAPIキーを指定してください。inputフィールドの文字数は4096文字までです。

音声プリセットの指定

8種類のプリセットから声質を選択できます。例:aria(暖かく明確なナレーター)、nova(明るく活発)、luna(柔らかいストーリーテリング)、sage(落ち着いた解説)、felix(エネルギッシュなプロモ)、milo(親しみやすい会話)、atlas(ニュートラルなニュース)、orion(深みのあるドキュメンタリー)。

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

mp3形式での出力

response_formatをmp3に設定すると、圧縮済みの音声ファイルが返されます。生成された音声ファイルは直接ダウンロードまたは保存でき、学習コンテンツの制作効率を向上させます。

OpenAI SDKとの連携

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

本APIはOpenAIのspeechエンドポイントと同じリクエスト形状を持つため、OpenAI SDKをbase_urlを変更して利用できます。base_urlを https://api.playbt678.com/v1 に変更し、認証キーを設定するだけで連携可能です。

この設計により、PythonやNode.jsなどの標準ライブラリを使って、余計な学習コストなしに音声合成機能をプロジェクトに組み込むことができます。

base_urlの変更

SDKの初期化時に base_url を https://api.playbt678.com/v1 に設定します。これにより、標準的な POST /v1/audio/speech エンドポイントへリクエストが送信されます。

既存コードの流用

OpenAIの音声合成用コードスニペットをそのままコピーし、エンドポイントとキーのみを変更すれば動作します。JSONボディの構造(model, input, voice)は同一です。

互換性の確認

送信パラメータはOpenAIと同一ですが、利用可能なvoiceプリセットは当社の8種類に限定されます。modelは "tts-1" または "tts-1-hd" のみサポートします。

リクエストパラメータ

の音声波形イラスト: リクエストパラメータ

APIリクエストの核心は、model、voice、inputの3つのパラメータ制御にあります。これらを正しく設定することで、教育コンテンツに最適な音声品質とコストを調整できます。

model: tts-1 / tts-1-hd

modelにはtts-1またはtts-1-hdを指定します。両者は同一のエンジンと価格(100万文字あたり$10)を持ち、出力音质に違いはありません。

voice: 8つのプリセット

8つの音声プリセットから選択します。女性ボイス(aria, nova, luna, sage)と男性ボイス(felix, milo, atlas, orion)から、教材のトーンに合うものを選びます。

  • aria: 暖かく明確なナレーター
  • nova: 明るく活発なトーン
  • atlas: ニュース調の中立な声

input: テキストと文字数

inputフィールドに最大4,096文字のテキストを渡します。スペースや句読点も文字数にカウントされ、1リクエストあたりの上限を超えないよう注意が必要です。

レスポンスとフォーマット

の音声波形イラスト: レスポンスとフォーマット

APIリクエストが成功すると、レスポンスボディには音声データそのものが直接格納されます。JSONラッパーではなく、response_formatで指定した形式のファイルが返却されるため、ストリーミングや追加のパース処理は不要です。生成された音声ファイルはサーバーに保存されません、受信時にクライアント側で処理されます。

音声ファイルの返却

成功時のHTTPステータスは200です。レスポンスボディには音声バイナリデータのみが含まれ、メタデータやテキスト情報は含まれません。入力テキストの検証はAPI側で実行され、問題がなければ即座に音声ファイルが配信されます。

  • レスポンスボディは音声データのみ
  • 追加のJSON解析は不要
  • サーバー側への永続保存はない

mp3, wav, opus, flac, pcm

response_formatパラメータで出力形式を指定できます。mp3は容量が小さくWeb用途に適し、wavやflacは高品質な加工向けです。rawなpcm形式もサポートしており、既存の音声処理パイプラインとの連携が可能です。

各フォーマットは同一の音声エンジンで生成され、品質の差はありません。ただし、ファイルサイズと帯域コストのバランスから、多くのケースでmp3が推奨されます。

  • mp3: 軽量、Web向け
  • wav/flac: 高品質、編集向け
  • opus: 効率的な圧縮
  • pcm: rawデータ

ステータスコード

200は合成成功を示します。400はパラメータエラー、429はレートリミット超過、500はサーバーエラーです。エラー時はエラーメッセージが返却されるため、ログ記録やユーザー通知に利用できます。

音声生成が失敗した場合は課金が返還されるため、ステータコードによる明確な判定が重要です。

  • 200: Success
  • 400: Bad Request
  • 429: Too Many Requests
  • 500: Internal Server Error
レスポンスとフォーマット

レートリミットとエラー

の音声波形イラスト: レートリミットとエラー

音声合成APIのレートリミットは、APIキーあたり1分間最大60リクエストです。負荷が高い場合、リクエストはキューイングされ、処理待ちが発生する可能性があります。短くても合成には数秒かかり、長文ではリアルタイム速度(1秒あたり約25文字)に近づきます。

1分間60リクエスト

同時接続数やキューイングにより、実際の応答遅延が生じる場合があります。大量のテキストを短時間で処理する必要がある場合は、分割リクエストのタイミングを調整してください。

最初のチャージ前制限

初回利用時は1分間10リクエストの制限が適用されます。USDT(TRC-20)でのチャージが完了すると、制限が解除され通常の60リクエスト/分に向上します。

エラーコードの解釈

合成に失敗した場合、料金は全額返金されます。HTTPステータスコード429はレートリミット超過、500は内部エラーを示します。タイムアウト時はリトライロジックを実装してください。

  • 429: Rate limit exceeded
  • 500: Internal server error
  • 401: Invalid API key

音声の言語指定

の音声波形イラスト: 音声の言語指定

APIリクエストでは、languageパラメータを明示的に指定することで、音声の発音ロジックを制御できます。Latin文字のテキストはデフォルトで英語として検知されるため、スペイン語やポルトガル語などの場合、ISOコード(例: es, pt)の設定が必須です。

ISOコードの手動指定

対応する23言語のISOコードをlanguageフィールドに設定してください。例: 日本語ならja、韓国語ならko、ドイツ語ならde。これを指定することで、任意の音声プリセットがその言語の正しいアクセントで読み上げられます。

  • 例: POST bodyに { "language": "fr" } を追加

自動言語検知の制限

言語パラメータを省略した場合、システムは入力テキストの文字コードに基づいて言語を推測します。ラテン文字のテキストはデフォルトで英語として扱われるため、他のラテン文字言語(イタリア語やオランダ語など)を使用する場合は誤検知を防ぐためにも明示的な指定が推奨されます。

非対応言語の処理

ベトナム語、インドネシア語、タイ語、ウクライナ語、ルーマニア語、チェコ語、ベンガル語などは現在対応していません。これらを入力した場合、音声は生成されますが、発音は標準的な英語または別の主要言語のアクセントで処理される可能性があります。正確な発音が必要な場合は、対応言語リスト内の言語のみを使用してください。

エラーハンドリングの実装

の音声波形イラスト: エラーハンドリングの実装

API呼び出しでは、音声合成の完了や失敗に応じて異なるHTTPステータスコードが返されます。成功時は200 OK、リクエスト本体の形式誤りや未指定パラメータには400 Bad Request、認証キーの有効期限切れや不正な場合は401 Unauthorizedが返却されます。エラーレスポンスには原因を示すメッセージが含まれるため、ログに記録してデバッグに活用してください。

音声合成リクエストは処理に数秒を要する場合があります。特にキュー待ちが発生している場合は、タイムアウトが早期に切れると失敗とみなされる可能性があります。適切なタイムアウト値の設定と、ネットワーク環境に応じた再試行ロジックの実装が重要です。

HTTPステータスコード

合成失敗時にはステータス400または500番台が返されます。400系は入力テキストの文字数超過や無効なvoice指定など、リクエスト側の問題を示します。500系はサーバー側の一時的な障害です。エラーレスポンスの本文に含まれるエラーコードを確認し、具体的な修正処置を取ってください。

ステータス200 OKが返された場合、音声ファイルデータがレスポンスボディに含まれています。これをファイルとして保存するか、ストリームとして処理してください。

  • 200 OK: 正常終了、音声データ含む
  • 400 Bad Request: パラメータ誤り、文字数超過
  • 401 Unauthorized: APIキーが無効または期限切れ
  • 429 Too Many Requests: レートリミット超過
  • 500 Internal Server Error: サーバー側障害

タイムアウト処理

音声合成は通常数秒で完了しますが、混雑時にはキュー待ちで最大数十秒かかる場合があります。クライアント側のタイムアウト設定を10秒程度にすると、キュー待ち中にタイムアウトエラーが発生する可能性があります。そのため、API仕様に基づき、少なくとも30秒以上のタイムアウト値を設定することを推奨します。

ネットワークの不安定な環境では、タイムアウト値をさらに長く設定するか、再接続ロジックを組み合わせる必要があります。

リトライロジック

500番台のエラーやネットワークエラーが発生した場合は、指数バックオフ(Exponential Backoff)方式でリトライを実装してください。例えば、1秒、2秒、4秒と待機時間を延ばしながら再試行を行います。これにより、サーバー側の過負荷状態を回避しながら、安定した音声合成を実現できます。

リトライ回数は3回程度に制限し、それでも失敗した場合はユーザーにエラー通知を表示してください。

8つの音声を確認

以下の各サンプルは、同じ文章をこのAPIで生成したものです。 保持されるメタデータは、音声そのものやテキストの内容とは分離されており、個別のコンテンツ詳細を特定するために使用されることはありません。

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

23言語

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

出典および参考資料

  1. Wikipedia
  2. LibriVox public-domain audiobooks
  3. LibriTTS-R corpus (OpenSLR 141)
  4. curl documentation
  5. MDN: Web Speech API
  6. Creative Commons Attribution 4.0
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. IETF RFC 7845: Ogg Opus
  9. FFmpeg documentation
  10. openai-node on GitHub
  11. openai-python on GitHub
  12. OpenAI API reference: create speech

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