よくある質問
APIキーはどのように取得しますか?
https://hbaj.info/get-api-key/ でGoogleまたはメール登録によりアカウントを作成してください。完了するとダッシュボードにAPIキーが表示されます。キーは1アカウントにつき1つで、必要に応じて再発行可能です。再発行すると旧キーは即時無効になります。
最初のリクエストはどのように実行しますか?
https://hbaj.info/get-api-key/ で表示されるcurl例を参照してください。POST https://api.hbaj.info/v1/audio/speech へ、JSONボディでmodel、input、voice、response_formatを指定して送信します。認証にはAuthorizationヘッダーにBearerキーを設定します。
OpenAI SDKは使用できますか?
はい、公式OpenAI SDKがそのまま利用可能です。base_urlを https://api.hbaj.info/v1 に変更し、サイト発行のAPIキーを設定するだけで動作します。リクエスト形状はOpenAIのspeechエンドポイントと同一です。
base_urlの変更はどのように行いますか?
SDK初期化時にbase_urlパラメータを https://api.hbaj.info/v1 に設定します。これにより、既存のOpenAI互換コードをそのままYomikazeのAPIに接続できます。他のエンドポイントも同様にこのベースURLを使用します。
サポートされる音声形式は何ですか?
mp3、wav、opus、flac、pcmの5形式に対応しています。response_formatフィールドで指定できます。音声ファイルはレスポンスボディとして直接返却され、サーバーには保存されません。
エラーが発生した場合、どう処理しますか?
合成に失敗した場合は、課金された金額が全額返金されます。ステータスコードやレスポンスボディのエラーメッセージを確認し、リクエストパラメータ(例:文字数制限)を再確認してください。エラー時のみ返金対象となります。
レートリミットはどのくらいですか?
APIキーあたり1分間あたり60リクエストが制限されています。最初のトップアップ前は1分間10リクエストです。リクエストは順次処理されるため、負荷が高い場合はキュー待ちが発生する可能性があります。
音声とモデルの選択はどのようにしますか?
GET /v1/voices で利用可能な音声リストを確認できます。モデルはtts-1またはtts-1-hdから選択します。これらは同じエンジンで価格も同一です。8つのプリセットから用途に合わせてvoiceパラメータを設定します。
tts-1とtts-1-hdの違いは何ですか?
両者は同じエンジンを使用しており、価格も同一です。モデル名の違いはありますが、機能や音質に実質的な差はありません。どちらを指定しても同じ結果が得られます。
速度調整はどのように設定しますか?
speedパラメータで0.25から4.0の範囲で調整可能です。デフォルト値は指定されていません。値が範囲外の場合、エラーとなる可能性があります。
言語はどのように指定しますか?
languageパラメータにISOコードを指定します。指定しない場合、スクリプトに基づいて言語が推測されます。ラテン文字のテキストはデフォルトで英語とみなされるため、英語以外のラテン文字テキストでは明示的な指定が必要です。
サポートされる言語は何ですか?
アラビア語、中国語、デンマーク語、オランダ語、英語、フィンランド語、フランス語、ドイツ語、ギリシャ語、ヘブライ語、ヒンディー語、イタリア語、日本語、韓国語、マレー語、ノルウェー語、ポーランド語、ポルトガル語、ロシア語、スペイン語、スワヒリ語、スウェーデン語、トルコ語の23言語です。
音声ファイルはどのように受信しますか?
POSTリクエストへのレスポンスボディとして音声ファイルが直接返却されます。ファイルはサーバーに保存されず、即時受信します。指定したresponse_formatに従ってバイナリデータが返されます。
エラー時の返金条件は何ですか?
合成が失敗した場合、課金額は全額返金されます。正常に完了したリクエストは課金対象となります。返金は自動的に処理され、残高に反映されます。
最初のリクエスト
curl
curl https://api.hbaj.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.hbaj.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.hbaj.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 | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
APIキーの取得方法
YomikazeのAPIを利用するには、まずアカウントの作成が必要です。アクセシビリティや音声UI開発の初期設定として、適切な認証情報の取得が最初のステップとなります。
登録方法によって初期クレジットの有無が異なります。プロジェクトの開始前に、適切な登録フローを選択してAPIキーを取得してください。
Google認証での登録
Googleアカウントを使用して迅速にサインアップできます。この方法で登録すると、有効期限7日間の$0.50のトライアルクレジットが付与されます。約50,000文字の読み上げが可能であり、機能の確認に最適です。
メール登録での作成
メールアドレスとパスワードによる登録も可能です。ただし、この方法で作成されたアカウントにはトライアルクレジットが付与されません。本格的な開発や長期利用を見据えたアカウント作成に適しています。
APIキーの確認とコピー
ダッシュボードの「APIキー」ページで、独自のキーを確認できます。1つのアカウントにつき有効なキーは1つです。キーを再生成すると、旧キーは直ちに無効になります。
- キーは「tts-...」で始まります
- セキュリティのため保管場所を管理してください
最初のリクエスト例
APIキーの発行後、curlコマンドまたは公式SDKを用いて最初の音声生成リクエストを送信します。エンドポイントは https://api.hbaj.info/v1/audio/speech に固定され、認証情報はヘッダーに付与します。
リクエスト成功時、音声データはレスポンスボディに直接返されます。失敗した場合は課金されず、ステータスコードで原因を確認できます。
cURLコマンドの実行例
以下のコマンドは、"tts-1" モデルで「こんにちは」というテキストを生成する例です。APIキーは実際のものに入れ替えてください。
- curl -X POST "https://api.hbaj.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"}' \
- --output speech.mp3
JSONボディの構造
リクエストボディには必須項目として model、input、voice を指定します。model は "tts-1" または "tts-1-hd" を選択します。input は最大4096文字までのテキストです。
- 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の範囲の倍率
音声ファイルの受信
正常なリクエストに対して、サーバーは音声データをバイナリ形式で返します。生成時間はおおむね1秒あたり25文字程度の実時間速度です。
OpenAI SDKとの連携
YomikazeのAPIはOpenAIのspeechエンドポイントと同一の形状を採用しているため、既存のOpenAI SDKをそのまま利用できます。base_urlをhttps://api.hbaj.info/v1に変更するだけで、認証キーの形式やJSONボディの構造はそのまま維持されます。これにより、コードの変更を最小限に抑えながら音声合成機能を実装できます。
base_urlの変更方法
SDKの初期化時にbase_urlパラメータを https://api.hbaj.info/v1 に設定します。これにより、APIキーの形式は tts-... に変更されますが、リクエスト送信ロジックは変更の必要がありません。
公式SDKの利用方法
PythonやNode.jsなどの公式SDKを使用し、変更したbase_url経由で POST /v1/audio/speech を呼び出します。認証ヘッダーに Authorization: Bearer <YOUR_API_KEY> を設定するだけで動作します。
互換性の確認
リクエストボディの model、input、voice、response_format などのフィールドはOpenAIの仕様と同一です。既存のOpenAI用コードをYomikazeで動作させるには、エンドポイントの書き換えのみで対応可能です。
サポートされる形式
音声ファイルの出力形式はmp3, wav, opus, flac, pcmの5種類から選べます。各形式は生成される音声データの違いを決定します。
mp3, wav, opus, flac, pcm
Request bodyのresponse_formatフィールドで指定可能です。これらはAPIが返す音声ファイルのエンコーディング形式を定義します。
- mp3: 広く互換性のある圧縮形式
- wav: 無圧縮の高音質形式
- opus: 高圧縮・低ビットレート向け
- flac: 可逆圧縮の无损形式
- pcm: 生のオーディオデータ
音声形式の選択基準
用途に応じて適切な形式を選定してください。読み上げ音声の品質とファイルサイズのバランスを考慮することが重要です。
- Web配信にはmp3やopusが適しています
- 録音や編集にはwavやflacが推奨されます
- デバッグ用途にはpcmが有効です
形式ごとの特徴
mp3は一般的な再生環境で広く対応しています。wavは圧縮率の影響を受けず、元の音声をそのまま保持します。
- opusは帯域幅が限られる環境で有用です
- flacはアーカイブ用途に適しています
- pcmは後処理が容易な生データです
エラー処理とステータス
API呼び出し時のレスポンスステータコードとエラーメッセージを確認し、音声合成の成功または失敗を判断します。失敗したリクエストは即時に処理され、適切なエラーコードが返されます。
エラー内容に応じて、入力テキストやパラメータを修正して再送信してください。失敗時の返金条件も合わせて確認し、コスト管理を最適化しましょう。
HTTPステータコード
成功時は200、無効なリクエストは400、認証エラーは401、レート制限超過は429などが返されます。これらのコードを確認して、問題の原因を特定してください。
- 200: 成功
- 400: 無効なリクエスト
- 401: 認証エラー
- 429: レート制限超過
エラーメッセージの確認
レスポンスボディにはエラーの詳細な説明が含まれます。例えば、入力テキストが4096文字を超えている場合や、無効な音声ファイル形式が指定された場合など、具体的なエラーメッセージが返されます。
失敗時の返金条件
音声合成に失敗した場合、そのリクエストは無料で、請求されません。失敗したリクエストに対する料金は全額返金されるため、コストを心配する必要はありません。

レートリミットの確認
API利用における安定した音声生成を実現するため、レートリミット(1分間60リクエスト)を理解することが重要です。特に高齢者向け読書支援やアクセシビリティ対応では、大量のテキストを連続して処理するケースが多いため、適切なキュー管理が不可欠です。
制限値を超えた場合は、リクエストがキューに積まれ、処理順に待機されます。これにより、音声品質が低下することなく、安定したサービス提供が可能になります。
1分間60リクエストの制限
1つのAPIキーあたり、1分間に60リクエストまでの同時実行が可能です。これにより、短時間で多数のテキストを音声に変換する処理も安定して実行できます。
初回前の1分間10リクエスト
アカウント作成直後は、1分間10リクエストの制限が適用されます。これは初期負荷を軽減するための措置であり、最初のチャージ完了後は自動的に60リクエスト/分に引き上げられます。
キュー処理の影響
負荷が高い場合、リクエストはキューに積まれ、順次処理されます。これにより、音声の品質や速度が低下することなく、安定したサービス提供が可能です。
音声とモデルの選択
Yomikazeの音声合成エンジンでは、tts-1とtts-1-hdの2つのモデルが提供されますが、両者は同一のエンジンを使用しており、価格も同じです。音声品質や生成速度に差異はなく、ユーザーは要件に応じていずれかを選択可能です。
8種類の音声プリセットから、用途に合った声質を選定します。Narrator用途のariaや、会話的なmiloなど、用途に合わせた選択が可能です。
tts-1とtts-1-hdの違い
両モデルは同じ音声合成エンジンを採用しており、出力される音声の質や生成速度に差はありません。価格も$10/100万文字で統一されています。したがって、特別な要件がない限り、どちらを使用しても結果は同一です。
音声プリセットの選択
8つの音声プリセットから、アプリケーションの性質に合うものを選択します。例えば、ariaは明確なナレーター、lunaはストーリーテリングに適しており、アクセシビリティ対応の読み上げでも自然な聴き心地を提供します。
男声ではatlasがニュース向け、orionがドキュメンタリー風などの使い分けが可能です。すべての音声は、LibriTTS-R(CC BY 4.0)やLibriVoxの録音データに基づいています。
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
速度調整の設定
speedパラメータで再生速度を0.25から4.0の範囲で調整できます。高齢者向けのアクセシビリティ用途では、やや低速に設定することで可読性を向上させることができます。
ただし、速度の変更は生成速度に直接影響を与えません。通常、テキスト1秒あたりの生成コストは一定です。
言語と音声の指定
APIリクエストでは、languageパラメータで生成対象の言語を明示的に指定できます。指定がない場合、文字コードから言語が自動判定されます(ラテン文字のデフォルトは英語)。
非英語のラテン文字テキストでは、正しく認識させるために言語コードの設定が推奨されます。これにより、音声の発音精度が向上します。
言語コードの指定方法
リクエストボディにlanguageフィールド(ISO 639形式)を追加してください。これは音声エンジンに発音ルールを伝える重要なパラメータです。
自動判定と手動指定
パラメータ未設定時は、入力テキストの文字コードに基づいて言語が推測されます。ただし、推測が外れた場合、不自然な発音になる可能性があります。
- ラテン文字のデフォルトは英語として処理されます
- 非英語のラテン文字テキストには手動指定が推奨されます
サポート言語の確認
対応言語は23言語です。それ以外(ベトナム語、タイ語など)はサポート外です。すべての音声プリセットは、全サポート言語に対応しています。
- 英語、日本語、中国語、韓国語、スペイン語など23言語
- どの音声でも全言語で読み上げ可能です
8つの音声を確認
以下の各サンプルは、同じ文章をこのAPIで生成したものです。 権利関係が単純なため、高齢者向け読書支援アプリのような多くのユーザーが利用するサービスでも、ライセンス上の懸念が少なく安定して運用できます。
23言語
どの音声でも、これらの言語のいずれかを話します。
