よくある質問
APIキーはどこで取得できますか?
サイト内の「/get-api-key/」ページからGoogleまたはメールアドレスでサインアップすると、APIキーが発行されます。無料トライアルでは0.50ドルのクレジットが提供されます。キーはアカウントごとに1つだけ有効で、ダッシュボードで残高や使用状況を確認できます。
APIキーの再生成はすぐに反映されますか?
はい、新しいキーを発行すると、古いキーは直ちに無効になります。これにより、セキュリティを確保しながら簡単にキーを切り替えることができます。
OpenAI SDKはどのように使用しますか?
base_urlを「https://api.playh31.com/v1」に変更し、APIキーを設定するだけで公式OpenAI SDKが使用可能です。リクエスト形状はOpenAIのspeechエンドポイントと同じです。
curlコマンドの例はどこにありますか?
APIキー発行ページ(/get-api-key/)に、すぐに使えるcurlコマンドの例が記載されています。これを使って即座に音声生成をテストできます。
エラーが発生した場合、どのように対応しますか?
音声合成に失敗した場合、請求は全額返金されます。エラーメッセージを確認し、入力テキストやパラメータを確認して再試行してください。
レートリミットを超えた場合、どうなりますか?
1分あたり60リクエストの制限があります。制限を超えるとリクエストがキューに待機され、処理順に実行されます。最初のチャージ前は1分あたり10リクエストです。
音声ファイルの形式はどのように選択しますか?
mp3、wav、opus、flac、pcmのいずれかを選択できます。WordPressやブログへの埋め込みにはmp3が推奨されます。
言語を指定しない場合、どうなりますか?
言語が指定されない場合、文字に基づいて自動的に推測されます。ラテン文字のテキストはデフォルトで英語として扱われるため、英語以外のラテン文字テキストには言語コードを明示的に設定してください。
音声の速度はどのように調整しますか?
速度パラメータで0.25から4.0の範囲で調整可能です。デフォルト速度は1.0です。
音声のモデルはどのように選択しますか?
tts-1またはtts-1-hdを選択できます。両者は同じエンジンと価格を持ち、品質の違いはありません。通常はtts-1で十分です。
音声の声はどのように選択しますか?
8つのプリセットから選択できます。aria、nova、luna、sageは女性、felix、milo、atlas、orionは男性の声です。ブログのトーンに合った声を選んでください。
音声のフォーマットはどのように選択しますか?
mp3、wav、opus、flac、pcmのいずれかを指定できます。WordPressへの埋め込みにはmp3が最も一般的で、互換性も高いです。
音声の速度はどのように調整しますか?
速度パラメータで0.25から4.0の範囲で調整可能です。
音声のモデルはどのように選択しますか?
tts-1またはtts-1-hdを選択できます。両者は同じエンジンと価格を持ち、品質の違いはありません。
APIキーの取得と設定
WordPressで音声読み上げ機能を活用するには、まずAPIキーの取得が必須です。APIキーは、サイトの「/get-api-key/」ページから取得できます。Googleアカウントまたはメールアドレスでの登録により、アカウントを作成し、キーを発行できます。
キーは安全に保管し、WordPressの設定やコード内で適切に使用してください。このキーを使って、音声生成APIにアクセスし、ブログ記事やページのアクセシビリティ向上を実現します。
Googleアカウントでの登録
Googleアカウントを使って登録すると、すぐにAPIキーが利用可能になります。無料体験として0.50ドルのクレジットが与えられ、7日間の有効期間があります。
メールとパスワードでの登録
メールアドレスとパスワードで登録することもできます。この方法では、無料体験クレジットは付与されません。
APIキーは1アカウントにつき1つ有効で、新しいキーを発行すると古いキーは即時無効になります。
APIキーの保管
APIキーは安全に保管してください。WordPressの「functions.php」や設定ファイルに直接埋め込む際は、外部公開されないように注意してください。
キーを紛失した場合でも、新しいキーをいつでも発行できます。
WordPressへの組み込み方法
WordPressのテーマディレクトリにあるfunctions.phpにコードを追加することで、API呼び出しロジックをテーマに組み込むことができます。これにより、プラグインのインストールが不要になり、サイト構成をシンプルに保つことができます。
ショートコードを作成することで、投稿や固定ページ内の任意の位置に音声再生ボタンを配置できます。テンプレートファイルを変更すれば、サイト全体のヘッダーやフッターに音声読み上げ機能を一元的に適用することも可能です。
functions.phpへのコード追加
APIキーを環境変数または定数として定義し、HTTPクライアントを使用してhttps://api.playh31.com/v1/audio/speechへPOSTリクエストを送信します。レスポンスのオーディオデータを一時ファイルとして処理します。
- APIキーを
functions.php内で定義 - HTTP POSTリクエストの実装
- レスポンスデータの受信処理
ショートコードの作成
add_shortcode関数を使用してカスタムショートコードを登録します。ユーザーが[voicereader text="こんにちは"]のように記述すると、指定されたテキストの音声ファイルが生成され、HTMLの<audio>タグで埋め込まれます。
この方法により、ビジュアルエディタやブロックエディタから簡単に音声コンテンツを挿入でき、技術的な知識がなくてもブログ記事にアクセシビリティ機能を追加できます。
- ショートコードの登録
- テキストパラメータの受け取り
- HTML audioタグの生成
テンプレートファイルの変更
テーマのテンプレートファイル(header.phpなど)に直接コードを挿入することで、ページ読み込み時に自動的に音声読み上げ機能を提供できます。これにより、ユーザーが明示的にボタンをクリックしなくても、コンテンツの音声化が可能になります。
特定のページタイプやカテゴリーに対してのみ機能を表示させる条件分岐も実装可能です。
- テンプレートファイルへの直接埋め込み
- 条件付き表示の実装
- サイト全体の統一感の維持
OpenAI SDKの活用
OpenAI SDKは、当社の音声合成APIと完全に互換性があります。base_urlをapi.playh31.com/v1に変更するだけで、既存のコードをほぼそのまま利用可能です。これにより、特別なSDK開発の手間なく、WordPress環境に組み込むことができます。
SDKを利用することで、簡潔なコードで音声ファイルの生成リクエストを送信できます。エラーハンドリングも標準機能として備わっており、ネットワーク障害やレート制限時の処理を安定して実装できます。
base_urlの変更
SDK初期化時にbase_urlオプションを変更します。公式OpenAI SDKと同じインターフェースを使用するため、学習コストが低く、WordPressプラグインへの統合が容易です。
- base_url: https://api.playh31.com/v1
- 同じリクエスト形式を使用
- 既存のOpenAIコードと互換性
公式SDKのインストール
Node.js環境ではnpm、Python環境ではpipを使用してSDKをインストールします。これらは標準的なパッケージマネージャーを使用するため、WordPressサーバー環境に簡単に導入できます。
- npm install openai
- pip install openai
エラーハンドリング
SDKはネットワークエラーや認証失敗を標準例外として返します。try-catchブロックで捕捉し、ユーザーフレンドリーなエラーメッセージを表示することで、サイト訪問者の体験を損なわずに済みます。
curlコマンドの使用例
curlコマンドは、WordPressのサーバーサイド処理やAPIとの連携を素早くテストできる強力なツールです。このセクションでは、基本的な音声生成リクエストの送り方と、返される音声データの扱い方を実例で説明します。
OpenAI互換のAPI仕様に基づいているため、既存のスキルをそのまま活用できます。複雑なSDKのインストール不要で、ターミナルから即座に動作確認が可能です。
基本のリクエスト
以下のコマンドは、"こんにちは"というテキストをAria音声でmp3形式で生成する例です。APIキーは環境変数から取得することを想定しています。
```bash curl -X POST https://api.playh31.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "こんにちは", "voice": "aria", "response_format": "mp3"}' \ --output speech.mp3 ```
パラメータの説明
必須パラメータはmodel、input、voiceです。modelはtts-1またはtts-1-hdを指定します。テキストは4096文字まで可能です。
任意パラメータとしてspeed(0.25〜4.0)、response_format(mp3, wav, opus, flac, pcm)が指定できます。languageを明示的に設定することで、日本語テキストでも正確な発話を実現できます。
- model: tts-1 または tts-1-hd
- input: 生成対象のテキスト文字列
- voice: aria, nova, luna, sage, felix, milo, atlas, orion
- response_format: mp3, wav, opus, flac, pcm
- speed: 0.25 から 4.0 の範囲
- language: ja, en, de, es などのISOコード
レスポンスの処理
成功した場合、APIはバイナリデータの音声ファイルを返します。--outputオプションでファイルに保存するか、-o speech.mp3のように指定します。,
レスポンスヘッダーにはレート制限情報(X-RateLimit-Remaining`など)が含まれる場合があります。WordPressのバックエンド処理では、このバイナリデータを直接保存するか、一時ファイルとして扱います。
音声ファイルの管理
API経由で生成された音声ファイルは、サーバーの一時ディレクトリやローカル環境に保存されます。WordPressの場合はwp-content/uploads配下などに管理フォルダを設け、APIレスポンスとして返された音声データを書き込む形が一般的です。
ファイルはmp3、wav、opus、flac、pcmのいずれかの形式で取得可能ですが、WordPressで再生するにはmp3またはwavが推奨されます。生成されたファイルはAPIレスポンスとして返され、サーバー側には自動的に長期保存されません。
ファイルの保存場所
音声ファイルはAPIリクエストごとに一時的に生成されます。WordPressのテーマやプラグイン側で、wp-content/uploads/voice-reader/のような独自ディレクトリを作成し、そこにファイルを書き込むのが安全です。
ファイルはAPIのレスポンスとして即座に返されるため、サーバーのストレージに自動的に蓄積されるわけではありません。プラグインやカスタムコードで明示的に保存処理を実装する必要があります。
- 一時ファイルはAPI応答に含まれる
- サーバーへの自動保存は行われない
- 独自の保存ディレクトリを事前に作成する
ファイル名の命名規則
ファイル名は一意である必要があります。ユニークIDやタイムスタンプを付与することで、重複を防ぎます。例えば、post_id-voice_id-timestamp.mp3のような形式が有効です。
WordPressの投稿IDやカスタムフィールドの値を活用すると、特定のコンテンツと音声ファイルを関連付けやすくなります。ファイル拡張子は選択した形式(mp3、wavなど)に合わせてください。
- ユニークIDまたはタイムスタンプを使用
- 投稿IDをファイル名の一部にする
- 拡張子は選択した音声形式に合わせる
ファイルの削除
音声ファイルは自動的には削除されません。必要ない場合は、WordPressのメディアライブラリやサーバーのファイルシステムから手動で削除する必要があります。
プラグインを使用している場合は、関連する投稿が削除された際に音声ファイルも自動的に削除する機能を実装すると便利です。ストレージの節約につながります。
- 自動削除はされないため手動管理が必要
- 投稿削除時に音声も削除する実装が推奨
- 不要なファイルは定期的にクリーンアップする
パフォーマンスと最適化
WordPressで大量のテキストを音声に変換する際、同じコンテンツの再生は避けてキャッシュを活用しましょう。APIは1リクエストあたり最大4096文字まで対応しており、長文は分割して結合する必要があります。
非同期処理やバッチ処理を活用すれば、ページの読み込みを阻害せずに音声生成を完了できます。レートリミット(60リクエスト/分)を考慮し、キューを適切に管理してください。
キャッシュの利用
音声ファイルは一度生成すれば再利用可能です。WordPressのオブジェクトキャッシュやファイルキャッシュを活用し、API呼び出し回数を削減しましょう。これにより、コストとレイテンシを同時に抑えられます。
特にブログの固定コンテンツやよく使われる定型文は、キャッシュ対象に含めるのが効果的です。
- 同じテキストの再生回数を減らす
- サーバー負荷を軽減する
非同期処理
音声生成は時間がかかるため、JavaScriptのFetch APIやAJAXを用いてバックグラウンドで処理しましょう。ユーザーはページの遷移を待たず、音声の準備完了を待機できます。
WordPressのCronジョブやキューシステムを活用すれば、投稿公開時に自動的に音声を生成・保存するワークフローも構築可能です。
- ページの読み込み速度を維持
- ユーザー体験を向上させる
レートリミットの管理
APIキーあたり毎分60リクエストの制限があります。フリーランスが複数のサイトを運用する場合、リミットを超えないよう注意深く設計しましょう。短時間で大量のテキストを変換する際は、キューを積んで順番に処理します。
レートリミットに達した場合は、少し待機してから再試行するロジックを実装してください。
- 毎分60リクエストの制限を守る
- キュー方式で負荷を分散する
アクセシビリティの向上
音声読み上げ機能は、WordPressサイトにおけるアクセシビリティ向上の重要な要素です。特に視覚に障害のあるユーザーがブログのコンテンツを容易に理解できるよう、APIの音声合成技術を有効活用しましょう。
再生制御を適切に実装することで、ユーザーが音声の開始・停止・速度調整を自由に操作できるようになります。これにより、個々のニーズに合わせた快適な閲覧体験を提供できます。
視覚障害者への配慮
音声読み上げボタンを画面左上や見出し直後に配置し、キーボード操作でもアクセス可能にします。Altテキストを適切に設定し、スクリーンリーダーが音声コンテンツの存在を正しく認識させることが重要です。
音声の再生制御
速度パラメータ(0.25〜4.0)を活用し、ユーザーが再生速度を調整できるようにします。音声ファイルはmp3やwav形式で提供され、ブラウザ標準のオーディオプレイヤーと統合することで直感的な操作を実現します。
テキストと音声の同期
APIはテキストを音声に変換して返すため、テキストと音声の対応関係は保たれます。4096文字までのテキストを処理し、必要に応じて分割合成することで、長文でも途切れることなく聴取できます。

トラブルシューティング
WordPressでAPIを実装する際、エラーはつきものですが、原因を特定することで解決策が見えます。ここでは一般的な問題とその対処法を整理します。
特にレートリミットや音声生成の失敗は、利用効率に直結するため、適切なエラーハンドリングが重要です。
エラーコードの解釈
APIが返すエラーコードは、具体的な原因を示します。例えば、認証エラー(401)はAPIキーの誤りや期限切れを意味し、Authorizationヘッダーを見直してください。サーバーエラー(500)は一時的なもので、再試行すれば解決することが多いです。
- 401: APIキーを確認
- 429: レートリミット超過
- 500: サーバー側一時的エラー
レートリミットのエラー
1分間あたり60リクエストという制限があります。ショートコードで大量のテキストを処理する際、この制限に達するとエラーになります。特に初期段階(初回トップアップ前)は1分間10リクエストなので、注意が必要です。
制限を超えた場合は、バックオフ処理(待機後再試行)を実装するか、テキストを分割して送信することで回避できます。
- 60リクエスト/分(通常)
- 10リクエスト/分(初期)
- 再試行ロジックの導入
音声ファイルのエラー
音声ファイルの生成に失敗した場合、チャージは返金されます。ただし、入力テキストが4096文字を超えている場合、エラーになる可能性があります。その場合はテキストを分割して複数のリクエストを送信してください。
また、音声ファイルのダウンロードが失敗した場合は、ネットワーク接続を確認してください。一時的な通信障害により、ファイルの取得に失敗することがあります。
- 4096文字制限の確認
- テキストの分割送信
- ネットワーク接続の確認
セキュリティとプライバシー
APIキーはアカウントごとに1つだけ有効で、新しいキーを発行すると旧キーは即時無効になります。functions.phpや環境変数で管理し、リポジトリに直接コミットしないよう注意してください。
入力のテキストは音声生成にのみ使用され、学習データとしては再利用されません。生成された音声は即時レスポンスで返され、サーバーには保存されません。
APIキーの保護
APIキーは機密情報として扱ってください。WordPressのwp-config.phpや環境変数で管理し、公開リポジトリに含めないことが重要です。
- 新しいキー発行で旧キーは即時無効化
- 環境変数での管理を推奨
- リポジトリへのコミットを避ける
データの暗号化
API通信はHTTPS経由で行われます。入力テキストは音声生成専用であり、生成音声はサーバーに永続保存されません。
アクセスログの記録
課金と監査のために、リクエストの時刻、文字数、ステータスコードが記録されます。これにより、利用状況の透明性を確保しています。
カスタマイズと拡張
既存の8音声に加え、外部音声の追加は可能ですか?本APIではカスタム音声クローニング機能を提供していません。LibriTTS-RやLibriVox由来のライセンス済み音声を使用する仕組みです。
速度やフォーマットは柔軟に調整できますが、SSMLやカスタム発音辞書には対応していません。必要に応じてテキストを分割し、APIリクエストで制御してください。
独自音声の追加
カスタムクローニング機能は備えていません。既存の8種類の音声(aria, nova, luna, sage, felix, milo, atlas, orion)から選択します。
カスタムパラメータ
速度(0.25〜4.0倍)と形式(mp3, wav, opus, flac, pcm)は指定可能です。SSMLタグや発音記号はサポート外です。
機能の拡張
OpenAI SDKをベースURL変更で利用できます。PHPやPythonのライブラリを組み合わせ、WordPressのテンプレートやショートコードに統合してください。
音声ファイルの自動削除やキャッシュ機能はAPI側では管理しません。WordPressのメディアライブラリやデータベースで管理する必要があります。
サポートとリソース
公式ドキュメントとよくある質問ページは、実装の基本概念から具体的なコード例まで網羅しています。各ページにはリファレンスやヒントが記載されており、迷ったときの頼りになる情報源です。
ドキュメントへのリンク
APIのリファレンスやSDKの使用例は /docs/ で確認できます。
基本的な使い方の手順やパラメータの説明が詳しく記載されています。
- /docs/ でAPI仕様を確認
- コード例をコピー&ペースト可能
FAQへのリンク
よくある質問ページでは、一般的な技術的な疑問や価格に関する説明がまとめられています。
実装でよくある失敗例とその解決策も記載されています。
- 実装手順の確認
- よくあるエラーの解決策
お問い合わせ先
技術的なサポートはメールのみで行っています。電話やライブチャットはありません。
質問がある場合は /contact/ ページからお気軽にご連絡ください。
- メールサポートのみ対応
次のステップ
WordPressでVoiceReader JP APIを活用する最初のステップは、テスト環境での確認です。無料トライアルの$0.50クレジットで、短いテキストの音声生成を試し、APIキーとbase_urlの設定が正しいか検証しましょう。
問題がなければ本番環境へ移行し、実際のブログ記事や説明文で音声読み上げの品質を確認します。その後、モニタリングの設定を行い、APIキーの使用状況とレートリミット(1分間60リクエスト)を適正に管理して、快適なアクセシビリティ環境を整えましょう。
テスト環境での確認
まず、Googleアカウントまたはメールアドレスでアカウントを作成し、APIキーを取得します。テスト環境では、4096文字以内の短いテキストでAPIリクエストを送信し、音声ファイルの受信と再生を確認します。
OpenAI SDKのbase_urlをhttps://api.playh31.com/v1に変更し、正しく動作するか検証します。失敗時は課金されない点も確認しておきましょう。
- APIキーの取得と保管を確認
- base_urlの変更とSDK連携テスト
- 音声ファイルのダウンロードと再生確認
本番環境への移行
テストが完了したら、本番サイトのWordPressテンプレートやショートコードに反映させます。実際のブログ記事やページのテキストで、音声生成の速度と品質を確認します。
音声ファイルの保存場所や命名規則、キャッシュの有効化も本番環境で最終確認します。必要に応じて、非同期処理の設定を調整し、サイトの読み込み速度に影響が出ないよう最適化します。
- テンプレートファイルの変更と公開
- 音声ファイルの保存先と命名規則の確認
- キャッシュ設定と非同期処理の調整
モニタリングの設定
APIキーの使用状況と残高を定期的に確認し、レートリミット(1分間60リクエスト)を超えないように管理します。OpenAI SDKのエラーハンドリングを適切に設定し、音声生成の失敗時に備えます。
音声ファイルのアクセスログや生成メタデータを記録し、必要な場合に削除や整理を行います。これにより、サイトのパフォーマンスとプライバシーを維持しつつ、効率的にAPIを活用できます。
- APIキーの使用状況と残高の確認
- レートリミット(1分間60リクエスト)の管理
- エラーハンドリングとログ記録の設定
8つの音声を確認
以下の各サンプルは、同じ文章をこのAPIで生成したものです。 この方法により、ビジュアルエディタやブロックエディタから簡単に音声コンテンツを挿入でき、技術的な知識がなくてもブログ記事にアクセシビリティ機能を追加できます。
23言語
どの音声でも、これらの言語のいずれかを話します。
