音声合成APIの技術仕様と統合ガイド

作成者 TTS Logic編集部 · 更新日 2026-11-18

Yomikai APIは、難読症やアクセシビリティ要件に対応する出版ワークフローに音声合成を統合するためのAPIです。標準的なOpenAI互換エンドポイントを採用し、既存のシステムにシームレスに組み込むことができます。本ページでは、リクエストパラメータ、認証方式、エラーハンドリングの具体的な実装方法から、レートリミットやcurlコマンド例まで、開発者がAPIを正しく運用するために必要なすべての情報を網羅しています。

対象読者は、デジタル出版やアクセシビリティソリューションを構築するエンジニアおよび技術責任者です。8種類のプリセット音声やmp3、wav、opus、flac、pcmなどのフォーマット指定、そして60リクエスト/分のレートリミットなどの制約事項を正確に理解し、安定した音声生成パイプラインを構築するための根拠として、この仕様書をご利用ください。

音声合成APIの技術仕様と統合ガイド

よくある質問

APIのエンドポイントURLは?

音声合成のエンドポイントは「POST https://api.plays98.com/v1/audio/speech」です。音声リストやモデル情報は「GET /v1/voices」、「GET /v1/models」で取得できます。JSON形式の本文を送信し、音声ファイルを返却します。

Authorizationヘッダーの形式は?

認証ヘッダーは「Authorization: Bearer tts-...」の形式で指定します。アカウントには1つのアクティブなキーが割り当てられ、必要に応じて新しいキーを発行できます。旧キーは即時無効化されます。

modelパラメータの違いは?

モデルには「tts-1」と「tts-1-hd」の2種類があります。これらは同じエンジンを使用し、価格も同一です。機能や品質に違いはなく、どちらを指定しても結果は変わりません。

音声の速度調整範囲は?

速度パラメータは0.25から4.0の範囲で調整可能です。デフォルト速度は1.0です。これにより、読み上げのテンポを用途に合わせて細かく制御できます。

languageパラメータは必須ですか?

必須ではありません。指定しない場合、スクリプトから言語が推測されます。ラテン文字のテキストはデフォルトで英語とみなされるため、英語以外のラテン文字テキストには明示的な指定が必要です。

レスポンスフォーマットは指定できますか?

mp3、wav、opus、flac、pcmの5形式から指定可能です。各形式は音声データの圧縮方式や品質特性が異なりますが、APIの動作自体には影響しません。

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

はい、base_urlを「https://api.plays98.com/v1」に変更することで公式OpenAI SDKが利用可能です。リクエストの形状はOpenAIの音声エンドポイントと同じです。独自SDKは提供していません。

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

1分あたり60リクエスト(初回トップアップ前は10リクエスト)の制限があります。超過するとリクエストがキューに入れられ、順次処理されます。

最初のリクエスト

curl

curl https://api.plays98.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.plays98.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.plays98.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エンドポイント

本APIは標準的なOpenAI互換エンドポイントを採用しており、既存のデジタル出版ワークフローへの統合を容易にします。主要なエンドポイントを利用することで、音声合成の実行、音声リストの取得、モデル情報の参照が行えます。

POST /v1/audio/speech

POST /v1/audio/speech

テキストを音声に変換する主要エンドポイントです。JSONボディでモデル、入力テキスト、音声、フォーマットを指定し、音声ファイルを返却します。

GET /v1/voices

GET /v1/voices

利用可能な音声、言語、フォーマット、価格情報を取得します。出版物のアクセシビリティ要件に応じた音声プリセットの選定に使用します。

GET /v1/models

利用可能なモデル情報を取得します。tts-1とtts-1-hdのエンジン仕様を確認するために使用します。

認証方式

の音声波形イラスト: 認証方式

認証には Authorization: Bearer tts-... ヘッダーを使用します。各アカウントでは1つのアクティブなAPIキーのみが有効であり、既存のキーは新しいキーが発行された瞬間に機能しなくなります。

不要になったキーは即座に無効化され、セキュリティリスクを最小限に抑えます。

Bearerトークンの設定

APIリクエストのヘッダーに Authorization: Bearer {your_api_key} を設定してください。OpenAI互換のSDKを使用する場合、base_url を https://api.plays98.com/v1 に変更するだけで認証は完了します。

この形式により、既存のデジタル出版システムとの統合が容易になります。キーはアカウントごとに一意であり、音声生成を制御できます。

  • ヘッダー名: Authorization
  • 形式: Bearer {API_KEY}
  • 有効範囲: アカウント単一

APIキーの生成と再生成

ダッシュボードからいつでも新しいAPIキーを発行できます。新しいキーが生成されると、それまで使用していた古いキーは即座に無効になります。これにより、キーの漏洩時でも即時に対応可能です。

キーの再生成は、出版システムのセキュリティポリシーに従った定期的なローテーションや、特定のプロジェクトごとの分離に利用できます。履歴は保持されません。

  • 新しいキー発行で旧キーは即停止
  • 履歴は保持されない
  • ダッシュボードから管理

キーの有効期限と停止

APIキーには期限切れの概念はありません。キーは手動で再生成されるまで有効です。ただし、新しいキーを発行すると旧キーは即時に使用不能になります。

これにより、長期にわたる出版プロジェクトでも、セキュリティレベルを維持したままAPI接続を継続できます。不要なキーが残り続けることがありません。

  • 期限切れなし
  • 再生成で旧キー即停止
  • 自動失効なし

リクエストパラメータ

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

APIリクエストには必須パラメータとしてモデルの選択、合成対象テキスト、音声プリセットの設定が必要です。各パラメータはJSONボディ内で指定し、システムが音声ファイルを生成します。

長文の処理が必要な場合は、4096文字の制限内で分割し、後で音声ファイルを結合する必要があります。短文の場合は生成に数秒、長文では実時間速度で処理されます。

model: tts-1 と tts-1-hd

利用可能なモデルは"tts-1"と"tts-1-hd"の2種類です。両モデルは同じエンジンと価格(100万文字あたり10米ドル)を採用しており、機能に差異はありません。

品質や速度の違いを重視しない場合、どちらのモデルを指定しても同等の結果が得られます。コスト面での違いもないため、既存のワークフローに合わせて任意のモデルを選択可能です。

input: テキスト(最大4096文字)

合成対象のテキストは"input"フィールドに指定します。1つのリクエストで処理できる最大文字数は4096文字です。スペースや句読点も文字数としてカウントされます。

4096文字を超える文章を処理する場合は、クライアント側で複数のリクエストに分割し、生成された音声ファイルを結合する必要があります。この分割処理はAPI内部ではなく、実装側で行う必要があります。

voice: 8種類のプリセット指定

音声プリセットは8種類から選択できます。女性ボイスはaria(暖かみのあるナレーター)、nova(明るく活発)、luna(柔らかいストーリーテリング)、sage(落ち着いた指示)です。男性ボイスはfelix(エネルギッシュなプロモーション)、milo(フレンドリーな会話)、atlas(中立なニュース)、orion(深みのあるドキュメンタリー)です。

どの音声でも、23言語に対応しています。言語を指定しない場合、ラテン文字は英語、それ以外の文字は自動検出されます。非英語のラテン文字テキストでは、明示的に"language"パラメータの設定を推奨します。

  • aria, nova, luna, sage(女性)
  • felix, milo, atlas, orion(男性)

レスポンスフォーマット

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

APIは、指定されたresponse_formatに従って音声ファイルをバイナリデータとして返します。対応形式はmp3、wav、opus、flac、pcmの5種類です。各ファイルは合成された音声そのものであり、メタデータは含まれません。

生成された音声ファイルには合成音声を示す不可聴の透かしが埋め込まれています。API呼び出し元は、返されたバイナリデータを直接ファイルとして保存するか、ストリームとして処理します。

mp3, wav, opus, flac, pcm

出力フォーマットはリクエストパラメータで指定可能です。mp3とwavは広く互換性があり、opusは帯域幅を節約します。flacとpcmはロスレス形式です。

出版ワークフローでは、最終媒体の要件に応じて適切な形式を選択します。すべての形式は同等の品質で生成され、追加のエンコードコストは発生しません。

音声データのバイナリ返却

レスポンスボディには音声ファイルのバイナリデータが格納されます。JSONラッパーではなく、生データが返されるため、クライアント側で適切なヘッダ処理が必要です。

生成された音声はサーバー側に永続保存されません。レスポンス受信後、クライアント環境でのみ保持されます。

ステータスコードの意味

成功時はHTTP 200が返され、音声データがボディに含まれます。失敗時は400または500番台のエラーコードが返されます。

合成処理に失敗した場合は、使用した文字数分の課金は行われません。料金は全額返金または残高から減算されません。

OpenAI SDKとの連携

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

本APIはOpenAIの音声合成エンドポイントと互換性があります。既存のOpenAI SDKを使用する際、base_urlをhttps://api.plays98.com/v1に変更し、APIキーを設定するだけで統合が可能です。

base_urlの変更方法

SDKの初期化パラメータでベースURLを上書きします。これにより、標準的なOpenAIライブラリがYomikaiのエンドポイントへリクエストを送信します。

互換性の確認

リクエスト形状はOpenAIと同一です。JSONボディのmodel, input, voiceフィールドはそのまま利用可能です。

公式SDKの直接使用

PythonやNode.jsなどの公式SDKをそのまま利用できます。追加のラッパーや独自の実装不要で、既存のワークフローに組み込めます。

OpenAI SDKとの連携

レートリミットとキュー

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

1つのAPIキーあたり、最大60リクエスト/分のレートリミットが適用されます。これは1分あたりの処理件数の上限を示すものです。

初回チャージ完了前、またはトライアルクレジット利用中のアカウントについては、レートリミットが1分あたり10リクエストに制限されます。

60リクエスト/分の制限

1つのAPIキーあたり、最大60リクエスト/分のレートリミットが適用されます。これは1分あたりの処理件数の上限を示すものであり、それを超えたリクエストはエラーとして返却されます。

初回チャージ完了前、またはトライアルクレジット利用中のアカウントについては、レートリミットが1分あたり10リクエストに制限されます。これはバッチ処理の効率化を図るための仕様です。

  • 1キーあたりの最大処理件数:60リクエスト/分
  • 初回チャージ前の制限:10リクエスト/分
  • リミット超過時はキューに待機

初回チャージ前の10リクエスト/分

アカウント作成直後や、チャージ前の状態では、1分あたり10リクエストまでの制限が適用されます。トライアルクレジット($0.50)を使用する際も同様の制限が維持されます。

この制限は、リソースの公平な配分とシステム安定性の確保を目的としています。チャージが完了すると、自動的に60リクエスト/分の制限へと緩和されます。

キュー待機の仕組み

リクエストは一度に並列処理されず、順次処理されます。特に長時間のテキスト合成や、多数のリクエストが集中する状況では、キューに待機する可能性があります。

合成が完了するまでの時間は、テキストの長さに比例して増加します。短めのフレーズでも数秒を要することがあり、キュー待ちによりさらに遅延する場合もあります。

処理待ちの時間制限は設定されておらず、キューが解消次第、順次処理が実行されます。ただし、負荷が高い状況では、リアルタイムでの処理が困難になる場合があります。

  • リクエストは順次処理(並列処理ではない)
  • キュー待機により、処理時間が延長される場合あり
  • 長時間テキストでは、リアルタイム処理が困難な場合も

エラーハンドリング

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

APIはリクエストの処理状況に応じて、適切なHTTPステータスコードを返却します。合成処理が正常に完了しなかった場合、またはサーバー側の一時的なエラーにより音声ファイルが生成されなかった場合、該当リクエストの料金は全額返金されます。これは失敗したリクエストに対しては課金しないという当社の方針に基づいています。

ただし、入力テキストの形式が不正である場合や、APIキーの認証に失敗した場合は、返金対象外となります。各エラーケースに応じた具体的なレスポンスボディが含まれますので、アプリケーションのエラー処理ロジックでステータスコードを判定してください。

合成失敗時の返金処理

音声合成の処理中に予期せぬエラーが発生した場合、サーバーは該当リクエストに対して課金を行いません。返金は自動的にアカウント残高に反映されますので、別途請求の確認や申請の手続きは必要ありません。これにより、不正確な音声ファイルや破損したデータに対して顧客が負担を負うことを防ぎます。

失敗の理由としては、内部サーバーエラーやタイムアウトなどが考えられますが、これらは全て無料の対象となります。正常に完了したリクエストのみがチャージの対象となるため、正確な課金メカニズムが保証されます。

  • 合成失敗時のみ料金が返金される
  • 返金は自動的にアカウント残高に反映される
  • 追加の手続きや申請は不要

入力テキストの文字数超過

1つのリクエストで送信できるテキストの最大長は4096文字です。これを超える長さのテキストを送信した場合、エラーレスポンスが返されます。エラーが発生したため、そのリクエストに対する課金は行われません。

長文のコンテンツを音声に変換する場合は、クライアント側で4096文字ごとにテキストを分割し、複数のリクエストを送信する必要があります。分割された各音声ファイルは、アプリケーション側で結合して使用してください。

  • 最大入力文字数は4096文字
  • 超過時はエラーレスポンスが返る
  • エラー時は課金されない

無効なAPIキーのエラー

リクエストヘッダーに指定されたAPIキーが存在しない、または無効な形式である場合、HTTP 401 Unauthorizedが返されます。また、キーが期限切れまたは無効化されている場合も同様のエラーとなります。

キーの再生成を行うと、以前のキーは即座に無効になります。古いキーを使用してリクエストを送信すると、認証エラーが発生します。正しいAPIキーを使用してリクエストを送信してください。

  • 無効なキーでは401エラーを返す
  • キー再生成後は旧キーは即時無効
  • 正しいキーでの認証が必要

curlコマンド例

の音声波形イラスト: curlコマンド例

APIとの連携検証にはcurlが有効です。以下に、基本的な音声合成リクエストから高度なパラメータ指定までの例を示します。

各コマンドは、認証キーとエンドポイントの構成が正しく設定されていることを前提としています。

基本リクエストの例

最も単純な形式では、モデル、入力テキスト、音声のみを指定します。

  • curl -X POST https://api.plays98.com/v1/audio/speech \ -H "Authorization: Bearer tts-your-api-key" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "こんにちは、世界", "voice": "aria"}'

パラメータ付きリクエスト

速度調整や言語の明示的指定が必要な場合は、以下のパラメータを追加します。

  • curl -X POST https://api.plays98.com/v1/audio/speech \ -H "Authorization: Bearer tts-your-api-key" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "This is a test", "voice": "nova", "speed": 1.2, "language": "en"}'

音声フォーマットの指定

,

音声フォーマットの指定

出力形式をwavやflacに指定するには、response_formatフィールドを設定します。

生成された音声ファイルはレスポンスボディとして返されます。

  • curl -X POST https://api.plays98.com/v1/audio/speech \ -H "Authorization: Bearer tts-your-api-key" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1-hd", "input": "High quality audio", "voice": "atlas", "response_format": "wav"}'

8つの音声を確認

以下の各サンプルは、同じ文章をこのAPIで生成したものです。

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

23言語

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

出典および参考資料

  1. Wikipedia
  2. FFmpeg documentation
  3. Creative Commons Attribution 4.0
  4. LibriTTS-R paper (arXiv 2305.18802)
  5. Python documentation
  6. IETF RFC 7845: Ogg Opus
  7. openai-python on GitHub
  8. OpenAI API reference: create speech
  9. LibriVox public-domain audiobooks
  10. curl documentation
  11. ISO 639 language codes
  12. Tether (USDT)

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