メディアガイド
音声とリアルタイム
音声の生成、文字起こし、音声翻訳、またはリアルタイムセッションの開始
結果がファイルまたはテキストである場合は、オーディオエンドポイントを使用してください。ライブの双方向音声体験には、リアルタイムWebSocketエンドポイントを使用します。
エンドポイントの選択
| 用途 | エンドポイント | 使用タイミング |
|---|---|---|
| テキスト読み上げ (TTS) | POST /v1/audio/speech | テキストから音声ファイルが必要な場合。 |
| 文字起こし | POST /v1/audio/transcriptions | 音声ファイルからテキストが必要な場合。 |
| 音声翻訳 | POST /v1/audio/translations | 音声ファイルから翻訳されたテキストが必要な場合。 |
| リアルタイムWebSocket | WS /v1/realtime?model={model} | WebSocket経由で双方向のストリーミング音声が必要な場合。通常の GET /v1/realtime はメタデータのみを返します。 |
モデルの選択
モデルをハードコーディングするのではなく、現在のモデルリストを読み取ってください。ソケットを開く前に、選択したモデルの詳細でリアルタイムサポートが有効か確認してください。
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"音声リクエスト
音声生成(Speech)は、HTTPレスポンスで音声を返します。文字起こしと翻訳は、最終的なテキストまたは受け付けられたタスクを返す場合があります。レスポンスボディに最終的なテキストではなくタスクIDとステータスが含まれている場合は、そのIDを保存し、完了または失敗するまで GET /v1/tasks/{id} をポーリングしてください。大きなファイルの場合は十分な時間を確保し、Request IDを保持してください。
音声結果のURLはTokenLabのメディア結果URLであり、30日間有効です。media_retention.items は各アイテムの保存ステータスと expires_at を報告します。保存ステータスが時間内に判明しない場合、レスポンスから media_retention が省略されることがありますが、URLは引き続き機能します。インラインまたはバイナリの音声レスポンスは、このURLコピー保持の対象外です。データ保持を参照してください。
curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-tts",
"voice": "eve",
"input": "Welcome to TokenLab."
}' \
--output speech.mp3リアルタイムセッション
クエリ文字列にモデルを指定し、AuthorizationヘッダーにAPIキーを含めてWebSocketを開きます。選択したリアルタイムモデルのドキュメントに従ってイベント形式を維持し、セッションが完了したらソケットを閉じます。
セッションは最大1時間継続します。その後、サーバーはコード 1000、理由 session_timeout でソケットを閉じます。単一のメッセージは最大32 MiBまで可能です。これを超えるメッセージは、コード 1009 でソケットを閉じます。grok-voice-think-fast-2.0 などの一部のリアルタイムモデルは、音声フレームとセッション更新のみを受け付けます。テキスト入力アイテムは unsupported_realtime_text_input エラーを返し、コード 1008 でソケットを閉じます。
このガイドはWebSocketサブセットのみを対象としています。TokenLabは現在、OpenAI Realtime RESTクライアントシークレット、翻訳クライアントシークレット、Calls、またはレガシーなベータ版セッション管理エンドポイントを提供していません。
以下のサーバーサイドの例では、ws をインストールし、TOKENLAB_REALTIME_MODEL に /v1/realtime を宣言している現在のモデルを設定してください。サーバー環境で TOKENLAB_API_KEY を提供してください。名前だけではリアルタイムサポートは確立されません。
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'));進捗状況を安全に表示する
- リフレッシュ時に同じリクエストを再実行するのではなく、生成された音声ファイルを保存してください。
- 文字起こしや翻訳では、API呼び出しが同期的な場合でも、アップロード中や処理中の状態を表示してください。
- リアルタイム通信では、クローズイベントを処理し、ユーザーが新しいセッションを開始した後にのみ再接続してください。
- 音声のテキスト入力にAPIキー、プライベートURL、アカウントのシークレットを含めないでください。
APIリファレンス
| トピック | リファレンス |
|---|---|
| 音声生成 (Create Speech) | 音声を作成 |
| 文字起こし (Create Transcription) | 文字起こしの作成 |
| 音声翻訳 (Create Translation) | 翻訳の作成 |
| リアルタイムWebSocket | Realtime WebSocket |
| モデル一覧 (List Models) | モデル一覧の取得 |
| 請求と価格 (Billing & Pricing) | Billing & Pricing |