OpenAI Realtime Transcription

Realtime Transcription は、持続的な WebSocket 接続で音声を継続的に受信し、音声項目ごとに差分テキストと確定済みの文字起こしを返します。ライブ字幕、会議メモ、通話の文字起こし、音声入力に適しています。録音済み音声を 1 回のリクエストでアップロードする場合は、Audio Transcriptions API を使用してください。

gpt-live-transcribe は低遅延の差分文字起こし向けです。gpt-transcribe は、発話区間全体の送信後に高精度で文字起こしする用途に適しており、最終イベントで検出言語を返せます。接続 URL とセッション設定では同じモデルを使用してください。

認証と接続

サーバーアプリケーションは、WebSocket ハンドシェイクで Bearer API キーを使用します。

通常のブラウザでは、WebSocket API の Authorization Header を任意に設定できません。長期 API キーをフロントエンド HTML、JavaScript、クライアントアプリのバンドルに含めないでください。ブラウザ製品では、信頼できるバックエンドを経由するか、管理された短期認証情報の仕組みを使用してください。

入力音声の要件

このページの例では、Header なし、モノラル、24 kHz、PCM16 little-endian 音声を使用します。input_audio_buffer.append の audio は生の PCM Byte を含む Base64 文字列であり、WAV ファイルなどの音声コンテナではありません。

一定サイズの小さな音声チャンクをリアルタイムで送信してください。1 イベントは 15 MiB を超えないようにします。音声形式、サンプルレート、コンテナ処理が正しくない場合、文字起こしに失敗することがあります。

セッション設定

session.update では、session.type を transcription に設定します。文字起こし設定は session.audio.input.transcription に配置します。

ヘッドセットには noise_reduction.type=near_field、会議室やノート PC のマイクには far_field を使用します。ノイズ低減を無効にする場合は null に設定します。

手動 Commit とサーバー VAD

• turn_detection: null：音声送信後、クライアントが input_audio_buffer.commit を呼び出します。アプリケーション側で区間を明示的に制御する場合に使用します。
• サーバー VAD：しきい値、Speech Prefix、無音時間を設定し、サーバーが発話の開始と終了を自動検出するようにします。

手動モードでは、空のバッファを Commit しないでください。VAD を有効にした場合、speech_started と speech_stopped を録音 UI の更新に使用できますが、最終的な文字起こしには completed イベントを使用してください。

接続例

以下の例では、audio.pcm があらかじめ 24 kHz、モノラル、PCM16 の生音声に変換されているものとします。リアルタイムアプリケーションでは、録音全体を一度に読み込まず、小さな音声チャンクを継続的に送信してください。

import fs from 'node:fs';
import WebSocket from 'ws';

const ws = new WebSocket('wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID', {
  headers: {
    Authorization: 'Bearer your-api-key',
  },
});

ws.on('open', async () => {
  ws.send(JSON.stringify({
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "noise_reduction": { "type": "near_field" },
        "transcription": {
          "model": "MODEL_ID",
          "prompt": "日本語のカスタマーサポート通話",
          "keywords": ["AGTCloud", "API ゲートウェイ"],
          "languages": ["zh-cn", "en"]
        },
        "turn_detection": null
      }
    }
  }
}));

  const audio = fs.createReadStream('audio.pcm', { highWaterMark: 4800 });
  for await (const chunk of audio) {
    ws.send(JSON.stringify({
      type: 'input_audio_buffer.append',
      audio: chunk.toString('base64'),
    }));
    await new Promise((resolve) => setTimeout(resolve, 100));
  }
  ws.send(JSON.stringify({ type: 'input_audio_buffer.commit' }));
});

ws.on('message', (message) => {
  const event = JSON.parse(message.toString());
  if (event.type.endsWith('.delta')) process.stdout.write(event.delta);
  if (event.type.endsWith('.completed')) console.log('\n', event.transcript);
});

イベントリファレンス

クライアントはセッションイベントと音声バッファイベントで入力を制御します。サーバーは差分テキスト、確定テキスト、エラーを Item ID に関連付けます。複数の音声項目は順不同で完了する場合があるため、item_id ごとにテキストを集約してください。

{
  "event_id": "evt_session_001",
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "noise_reduction": {
          "type": "near_field"
        },
        "transcription": {
          "model": "MODEL_ID",
          "prompt": "日本語のカスタマーサポート通話",
          "keywords": [
            "AGTCloud",
            "API ゲートウェイ"
          ],
          "languages": [
            "zh-cn",
            "en"
          ],
          "delay": "low"
        },
        "turn_detection": null
      }
    }
  }
}

エラー処理と復旧

差分テキストは後続の結果で修正される場合があります。delta の値を変更不能な記録へ直接保存しないでください。現在の音声項目の最終テキストとして扱うのは、completed の transcript だけです。