メディアガイド
オーディオとリアルタイム
音声アプリ向けに、音声生成、文字起こし、翻訳、リアルタイム WebSocket を選びます。
オーディオ処理は二つに分かれます。テキスト読み上げ、文字起こし、音声翻訳のようなファイル型の処理は Audio endpoint を使います。低遅延の対話音声やリアルタイムのマルチモーダルイベントが必要な場合は Realtime WebSocket を使います。
ワークフローを選ぶ
| ワークフロー | Endpoint | 使う場面 |
|---|---|---|
| テキスト読み上げ | POST /v1/audio/speech | テキストから音声ファイルを作る場合。 |
| 文字起こし | POST /v1/audio/transcriptions | 音声ファイルからテキストを得る場合。 |
| 音声翻訳 | POST /v1/audio/translations | 音声ファイルから翻訳済みテキストを得る場合。 |
| リアルタイムセッション | GET /v1/realtime | 双方向ストリーミング音声またはリアルタイムイベントが必要な場合。 |
モデルを確認する
モデル一覧をクライアントに固定しないでください。音声生成と文字起こしは推奨モデルを使い、リアルタイム対応は socket を開く前にモデル詳細で確認します。
curl "https://api.tokenlab.sh/v1/models?recommended_for=tts" \
-H "Authorization: Bearer sk-your-api-key"
curl "https://api.tokenlab.sh/v1/models?recommended_for=stt" \
-H "Authorization: Bearer sk-your-api-key"同期オーディオリクエスト
音声合成は HTTP 応答で音声を返します。文字起こしと翻訳は最終テキストまたは受理済みタスクを返します。最終テキストの代わりにタスク ID と状態がある場合、ID を保存して poll_url を完了または失敗まで確認してください。大きなファイルには十分なタイムアウトを設け、Request ID を保存します。
curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "tts-1-hd",
"voice": "nova",
"input": "Welcome to TokenLab."
}' \
--output speech.mp3リアルタイムセッション
WebSocket では query string に model、Authorization header に API key を入れます。選択したリアルタイムモデルのドキュメントに沿ったイベント形式を使い、完了時に socket を閉じます。
このガイドは WebSocket サブセットのみを対象にしています。TokenLab は現在、OpenAI Realtime REST の client secret、translation client secret、Calls、legacy beta session 管理エンドポイントを提供していません。
以下のサーバー側の例では ws をインストールし、詳細に /v1/realtime が記載された現行モデルを TOKENLAB_REALTIME_MODEL に設定します。TOKENLAB_API_KEY はサーバー環境で渡してください。名前だけでは realtime 対応を判断できません。
npm install wsimport WebSocket from 'ws';
const model = process.env.TOKENLAB_REALTIME_MODEL;
const apiKey = process.env.TOKENLAB_API_KEY;
if (!model || !apiKey) throw new Error('Set TOKENLAB_REALTIME_MODEL and TOKENLAB_API_KEY');
const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', model);
const socket = new WebSocket(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
socket.on('message', (event) => console.log(event.toString()));
socket.on('error', (error) => console.error(error.message));
process.once('SIGINT', () => socket.close(1000, 'Client stopped'));状態管理
- 生成済み音声ファイルを保存し、更新時に同じリクエストを再実行しない。
- 文字起こしと翻訳は同期でもアップロード中・処理中の状態を表示する。
- リアルタイムでは close イベントを処理し、ユーザーが新しいセッションを始めた時だけ再接続する。
- API key、非公開 URL、アカウント秘密情報を音声テキスト入力に入れない。