よくある質問
APIキーはどのように取得しますか?
サイト内の/get-api-key/ページでGoogleまたはメールアドレスとパスワードでサインアップしてください。アカウント作成後、ダッシュボードでAPIキーを確認できます。キーは1アカウントにつき1つ有効で、新しいキーを発行すると古いキーは即時無効になります。
OpenAI SDKは使えますか?
はい、公式のOpenAI SDKを使用できます。base_urlを当サイトのAPIベースURLに変更し、APIキーを設定するだけで動作します。独自SDKやモバイルSDKはありませんが、標準的なHTTPクライアントやOpenAI SDKの互換性により容易に統合できます。
base_urlはどこに設定しますか?
base_urlには「https://api.retrospectos.info/v1」を設定してください。これにより、OpenAI SDKの互換エンドポイントを通じて音声生成リクエストを送信できます。他のエンドポイントもこのベースURL配下に配置されています。
curlコマンドの例を教えてください。
/get-api-key/ページに準備済みのcurl例が掲載されています。POST https://api.retrospectos.info/v1/audio/speech に対し、JSONボディでmodel、input、voiceなどを指定します。AuthorizationヘッダーにBearerトークンを設定してリクエストを送信してください。
エラーコードの意味は何ですか?
合成に失敗した場合は、請求は全額返金されます。エラーの詳細ページは別途ありませんが、HTTPステータスコードに従って処理してください。メタデータは請求のために保持されますが、生成された音声ファイル自体は保存されません。
レートリミットは?
1キーあたり1分間あたり60リクエストが制限されています。最初のチャージ前は1分間あたり10リクエストです。長文は4096文字ごとに分割して処理され、音声ファイルが結合されます。負荷が高い場合、リクエストはキューで待機することがあります。
音声ファイルの形式は選べますか?
mp3、wav、opus、flac、pcmの5形式から選択可能です。response_formatパラメータで指定します。各形式はAPIレスポンスで直接返され、ファイルは保存されません。必要なフォーマットに応じて適切な形式を指定して音声データを取得してください。
speedのパラメータは?
speedパラメータは0.25から4.0の範囲で調整できます。デフォルト値は1.0です。速度を変更すると、生成される音声の再生速度が変化します。テキストの長さに応じて適切な速度を設定してください。
最初のリクエスト
curl
curl https://api.retrospectos.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.retrospectos.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.retrospectos.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キーの取得
APIキーは、まずAPIエンドポイントへのアクセスを認証するために必要です。アカウント作成方法によって、初期のクレジット状態が異なります。
Googleログインでの取得
Googleアカウントでログインすると、即時に0.50ドルの試用クレジットが付与されます。これは約5万文字分に相当し、7日間有効です。
メール登録での取得
メールアドレスとパスワードで登録した場合は、試用クレジットは付与されません。直接使用可能な残高を確認してから利用を開始してください。
キーの再発行と無効化
安全のため、いつでも新しいAPIキーを発行できます。新しいキーを発行すると、それまで有効だった古いキーは即時に無効化されます。
既存のキーが漏洩した際や、異なる環境で使い分けたい場合に有効な機能です。
curlコマンドでのリクエスト
APIキーを取得したら、curlコマンドで実際に音声生成リクエストを送信できます。POSTエンドポイントにJSONボディを指定し、認証ヘッダーにBearerトークンを含めます。
この方法では、複雑なSDKのインストール不要で、すぐにAPIの動作を確認できます。
基本リクエストの例
以下のコマンドは、英会話の研修スクリプトを音声に変換する例です。modelは"tts-1"を、voiceは"nova"を指定しています。
curl -X POST "https://api.retrospectos.info/v1/audio/speech" -H "Authorization: Bearer tts-YOUR_KEY" -H "Content-Type: application/json" -d "{\"model\": \"tts-1\", \"input\": \"Welcome to the training session.\", \"voice\": \"nova\", \"response_format\": \"mp3\"}" -o output.mp3
音声ファイルのダウンロード
-o オプションにより、生成された音声ファイルがローカルに保存されます。
失敗したリクエストでは課金されません。
JSONレスポンスの確認
レスポンスボディには音声データそのものがバイナリで含まれます。エラー時はJSON形式で詳細なメッセージが返ります。
OpenAI SDKとの連携
公式のOpenAI SDKを使用して、既存のコードベースを最小限の変更で統合できます。SDKの動作原理はHTTP APIと同一であり、base_urlのみを当社のエンドポイントに変更するだけで連携可能です。
これにより、PythonやNode.jsの標準的なライブラリ経由で音声生成リクエストを送信でき、開発の効率化が図れます。
base_urlの変更
SDKの初期化時に、base_urlパラメータを https://api.retrospectos.info/v1 に設定します。認証キーは通常のBearerトークンとして渡すため、エンドポイントの仕様はOpenAIのspeechエンドポイントと互換性があります。
- base_url: https://api.retrospectos.info/v1
- 認証: Authorization: Bearer <your-api-key>
Python SDKの使用例
Python環境ではopenaiパッケージをインストールし、clientのbase_urlを上書きします。生成された音声ファイルはバイナリデータとして返されるため、ファイルシステムに保存するか、ストリーム処理します。
- pip install openai
- client = OpenAI(base_url="https://api.retrospectos.info/v1", api_key="tts-...")
Node.js SDKの使用例
Node.jsでは@openai/openaiパッケージを使用します。base_urlとapiKeyを指定することで、他のOpenAI互換エンドポイントと同様にメソッドを呼び出せます。
- npm install openai
- const openai = new OpenAI({ baseURL: 'https://api.retrospectos.info/v1', apiKey: 'tts-...' });
音声ファイルのフォーマット
音声ファイルの生成時には、用途に応じてresponse_formatパラメータで出力形式を選択できます。APIはmp3、wav、opus、flac、pcmの5形式に対応しており、配信環境や編集ワークフローに合わせた最適な形式を指定可能です。
MP3形式
mp3は最も汎用性の高い形式です。多くのメディアプレイヤーやWebブラウザで即時再生可能であり、ファイルサイズが小さいため、研修コンテンツのWeb配信や簡易的な音声配布に適しています。
WAV形式
wavは非圧縮のオーディオ形式です。音声データの劣化がなく、音声編集ソフトや動画制作パイプラインでの加工に最適です。品質を重視する教育リソースのアーカイブや、社内システムへの組み込み用途で推奨されます。
OPUS, FLAC, PCM
OPUSは低ビットレートでも高音質を維持し、効率的なデータ転送に適しています。FLACは可逆圧縮でファイルサイズを削減しつつ音質を保持し、PCMは生データとしてログ記録や高度な解析が必要な場合に利用します。
パラメータの設定
APIリクエストには、生成エンジン、音声の個性、再生速度、および言語の指定が必須です。これらを適切に設定することで、研修コンテンツのトーンやアクセントを正確に制御できます。
modelの指定
model パラメータには「tts-1」または「tts-1-hd」を指定します。両者は同じエンジンを使用し、価格も同一です。用途に応じて選択してください。
voiceの選択
8種類のプリセットから選択します。女性ボイスには「aria(暖かく明確なナレーター)」「nova(明るく活発なトーン)」「luna(柔らかく物語調)」「sage(落ち着きのある指示調)」があります。男性ボイスには「felix(エネルギーに満ちたプロモーション)」「milo(親しみやすい会話調)」「atlas(ニュートラルなニュース調)」「orion(深みのあるドキュメンタリー調)」が用意されています。
どの音声も全23言語に対応しており、日本語の研修資料にも適したトーンを選定できます。
- aria: 暖かく明確なナレーター
- nova: 明るく活発なトーン
- luna: 柔らかく物語調
- sage: 落ち着きのある指示調
- felix: エネルギーに満ちたプロモーション
- milo: 親しみやすい会話調
- atlas: ニュートラルなニュース調
- orion: 深みのあるドキュメンタリー調
speedとlanguage
speed は 0.25 から 4.0 の範囲で再生速度を調整できます。標準は 1.0 です。研修の内容に応じて、聞き取りやすい速度に調整してください。
language は任意の ISO 言語コードです。指定しない場合はスクリプトから言語が自動推測されます(ラテン文字はデフォルトで英語)。日本語や他の言語を使用する場合は、明示的に language を設定してください。

エラーハンドリング
API呼び出し時に発生するエラーは、主にレスポンスステータスコードとエラーメッセージで判断します。成功時(200)以外は、原因を特定してリクエストを修正してください。
一般的なエラーコード
401 UnauthorizedはAPIキーが不正または期限切れの場合です。400 Bad Requestはパラメータの形式誤りを示します。これらはドキュメントの仕様を確認して修正してください。
レートリミットのエラー
1分間あたりのリクエスト数が上限を超えると429エラーが発生します。通常は60リクエスト/分ですが、未課金時は10リクエスト/分に制限されます。一時的な待機後、再試行してください。
テキストの長さエラー
1リクエストあたりの入力テキストは4096文字までです。これを超えるとエラーが発生するため、アプリ側でテキストを分割して複数リクエストを送信する必要があります。
レートリミット
API利用時の安定性を保つため、レートリミットが設定されています。通常は1分間に60リクエストまで送信可能です。
初回利用時や課金前の制限、およびキューの仕組みを理解し、効率的な音声生成フローを構築してください。
1分あたりのリクエスト数
有効なAPIキーあたり、1分間に最大60リクエストまで送信できます。これを超えると、後続のリクエストは拒否されます(キュー待機ではありません)。
一度のAPI呼び出しで生成される音声ファイルは、通常の長さでは数秒から実時間程度の処理時間を要します。大量のテキストを短時間で生成する場合は、この制限を考慮して設計してください。
最初のトポアップ前の制限
アカウント作成直後、または初回のトップアップ(USDTによる入金)が完了するまでは、1分あたり10リクエストの制限が適用されます。
これは無料トライアル($0.50分)の利用中にも同様です。制限を解除するには、TRONネットワーク(TRC-20)を介してのトポアップが必要です。
キューの挙動
リクエストは順次処理されます。そのため、処理負荷が高い時間帯や、大量のリクエストが同時に発生した場合は、キューに待機する場合があります。
キュー待機中のリクエストも、最終的には正常に処理されます。ただし、応答までに通常よりも時間がかかることを想定して、クライアント側のタイムアウト設定を確認してください。
デバッグとテスト
APIの動作確認では、返却されるHTTPステータスコードとレスポンスヘッダーをまず確認してください。成功時は200 OK、パラメータ異常時は400 Bad Requestなど、エラー内容に応じたコードが返されます。
X-Request-Idは各リクエストに割り当てられる一意の識別子です。問題発生時にサポート窓口へ連絡する際、このIDを添付することで原因追跡が容易になります。
レスポンスヘッダー
正常な音声生成リクエストには、音声ファイルのデータとともに適切なヘッダーが含まれます。X-Request-Idフィールドには、そのリクエストを一意に特定する文字列が格納されています。
- X-Request-Id: 一意な識別子。エラー連絡時に必須。
ステータスコード
音声生成が完了するとステータスコード200が返され、音声データがボディに格納されて返却されます。パラメータの形式が正しくない場合や、無効な音声IDを指定した場合は400 Bad Requestが返ります。
ログの確認
レスポンスヘッダーやステータスコードを記録することで、音声生成の成否と所要時間を確認できます。X-Request-Idを活用すれば、後ほど発生したエラーの原因特定も迅速に行えます。
8つの音声を確認
以下の各サンプルは、同じ文章をこのAPIで生成したものです。 これを超える長文の研修資料を作成する場合は、クライアント側で適切な文字数に分割し、複数のリクエストを発行して生成された音声ファイルをつなぎ合わせる必要があります。
23言語
どの音声でも、これらの言語のいずれかを話します。
