AGTCloud API Docs
ガイドAPIリファレンス連携とリソース更新とヘルプ
リアルタイム

OpenAI Realtime

Realtime WebSocket 接続を通じて、リアルタイムのテキスト、音声、関数呼び出しを処理します。

OpenAI Realtime は、持続的な接続と双方向イベントを使用して、リアルタイムのテキスト、音声、関数呼び出しを処理します。クライアントはセッション、音声バッファ、会話項目、レスポンス制御の各イベントを送信し、サーバーはセッション状態、文字起こし、テキスト、音声、関数引数、エラーイベントを継続的に返します。

このページでは、主に WebSocket 接続を扱います。接続時に、MODEL_ID を現在のアカウントで利用でき、Realtime に対応するモデル ID に置き換えてください。

主な用途には、リアルタイム音声会話、会議のライブ文字起こし、音声アシスタント、リアルタイム翻訳、音声認識、対話型コーディング、サーバー側のリアルタイム連携があります。1 つの接続でテキストと音声の両方を送受信でき、イベントによって VAD、関数呼び出し、状態更新を制御します。

WSS
wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID

認証と接続

WebSocket 認証

サーバーアプリケーションは、Bearer API キーを使用して WSS 接続を確立し、ハンドシェイクリクエストに Realtime Beta Header を含めます。

項目値
接続 URLwss://api.agtcloud.cn/v1/realtime?model=MODEL_ID
AuthorizationBearer your-api-key
OpenAI-Betarealtime=v1

長期 API キーは、信頼できるサーバーでのみ使用してください。ブラウザ、モバイルアプリのバンドル、公開リポジトリには含めないでください。接続には必ず HTTPS/WSS を使用します。

一時トークン

クライアントが接続する前に、信頼できるサーバーから有効期間が 1 分で、1 回の接続に限定された一時トークンを作成できます。

POST https://api.agtcloud.cn/v1/realtime/sessions
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "model": "MODEL_ID",
  "voice": "verse"
}

接続フロー

基本的な WebSocket フローでは、サーバーが API キーを使って直接接続します。ハンドシェイクが成功すると、同じ接続上でクライアントイベントを送信し、サーバーイベントを受信します。

WebRTC フローでは、クライアントが最初にアプリケーションサーバーへ一時トークンを要求し、アプリケーションサーバーがセッションエンドポイントを呼び出してトークンを作成します。続いてクライアントが SDP Offer を作成して Realtime エンドポイントへ送信し、SDP Answer を受け取ります。JSON イベントは oai-events Data Channel を通じて送受信します。

WebSocket 接続例

以下の例では、Node.js、Python、イベント送信、イベント受信を示します。接続後、クライアントは JSON イベントを送信し、サーバーは JSON イベントを継続的に返します。

WSSWebSocket接続とイベント交換
import WebSocket from 'ws';

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

ws.on('open', () => {
  console.log('Connected to server.');
});

ws.on('message', (message) => {
  console.log(JSON.parse(message.toString()));
});

WebRTC 連携

現時点では WebSocket を推奨します。WebRTC を使用する前に、対象モデルが対応していることを確認してください。以下の例では、一時トークン、SDP、音声トラック、Data Channel を使用する基本的な接続構造を示します。

セッション、音声、会話

Realtime は、テキストのみ、音声のみ、テキストと音声を組み合わせた会話に対応します。セッション設定には、入出力音声形式、Voice、Temperature、最大出力長、ツール、VAD 設定を含められます。

  • 入出力音声形式:pcm16、g711_ulaw、g711_alaw。
  • Voice の例:alloy、echo、shimmer。
  • VAD 設定には、検出しきい値、Prefix Padding、無音時間が含まれます。
  • セッション、会話項目、Content Part、レスポンスイベントによって会話が進行します。

各イベントのフィールドは、以下のイベントブラウザで確認してください。共通パラメーターと値の範囲は「共通型」にまとめています。

イベントリファレンス

イベントを選択すると、フィールド定義と JSON 例を確認できます。イベント方向の切り替え、カテゴリーフィルター、イベント名検索も利用できます。

クライアントイベント · Session

session.update

セッションの既定設定を更新します。

フィールド型必須説明例
event_idstringいいえクライアントが生成したイベント識別子です。event_123
typestringいいえイベント種別です。session.update
modalitiesstring[]いいえモデルがレスポンスで使用できるモダリティです。["text", "audio"]
instructionsstringいいえモデル呼び出し前に適用するシステム指示です。"簡潔かつ正確に回答してください。"
voicestringいいえモデルが使用する Voice です。alloy、echo、shimmer
input_audio_formatstringいいえ入力音声形式です。pcm16、g711_ulaw、g711_alaw
output_audio_formatstringいいえ出力音声形式です。pcm16、g711_ulaw、g711_alaw
input_audio_transcription.modelstringいいえ文字起こしに使用するモデルです。whisper-1
turn_detection.typestringいいえ音声検出の種類です。server_vad
turn_detection.thresholdnumberいいえVAD の検出しきい値(0.0~1.0)です。0.8
turn_detection.prefix_padding_msintegerいいえ発話開始前に含める音声時間です。500
turn_detection.silence_duration_msintegerいいえ発話終了の検出に使用する無音時間です。1000
toolsarrayいいえモデルが利用できるツールの一覧です。[]
tool_choicestringいいえモデルがツールを選択する方法です。auto/none/required
temperaturenumberいいえモデルの Sampling Temperature です。0.8
max_output_tokensstring または integerいいえ1 回のレスポンスにおける最大 Token 数です。"inf"/4096
JSONの例
{
  "event_id": "event_123",
  "type": "session.update",
  "modalities": [
    "text",
    "audio"
  ],
  "instructions": "簡潔かつ正確に回答してください。",
  "voice": "alloy",
  "input_audio_format": "pcm16",
  "output_audio_format": "pcm16",
  "input_audio_transcription": {
    "model": "whisper-1"
  },
  "turn_detection": {
    "type": "server_vad",
    "threshold": 0.8,
    "prefix_padding_ms": 500,
    "silence_duration_ms": 1000
  },
  "tools": [],
  "tool_choice": "auto",
  "temperature": 0.8,
  "max_output_tokens": "inf"
}

共通型

以下では、Rate Limit、関数呼び出し、音声、VAD、ツール、モデル、イベント、セッション、会話項目、コンテンツ、レスポンス、文字起こし、音声ストリーム、WebRTC の共通パラメーターをまとめます。

Rate Limit イベントパラメーター4個のフィールド
フィールド型必須説明選択肢または例
namestringはいRate Limit 名です。例:requests_per_min
limitintegerはい制限値です。例:60
remainingintegerはい残りの利用可能量です。例:45
reset_secondsintegerはいリセットまでの秒数です。例:35
関数呼び出しパラメーター4個のフィールド
フィールド型必須説明選択肢または例
typestringはい関数の種類です。例:function
namestringはい関数名です。例:get_weather
descriptionstringいいえ関数の説明です。例:Get the current weather
parametersobjectはい関数パラメーターの定義です。例:{"type": "object", "properties": {...}}
音声形式パラメーター4個のフィールド
フィールド型必須説明選択肢または例
sample_rateinteger—サンプルレートです。選択肢:8000, 16000, 24000, 44100, 48000
channelsinteger—チャンネル数です。選択肢:1 (モノラル), 2 (ステレオ)
bits_per_sampleinteger—量子化 Bit 数です。選択肢:16 (pcm16), 8 (g711)
encodingstring—エンコード方式です。選択肢:pcm16, g711_ulaw, g711_alaw
音声検出パラメーター3個のフィールド
フィールド型必須説明選択肢または例
thresholdnumber—VAD の検出しきい値です。既定値:0.5、範囲:0.0-1.0
prefix_padding_msinteger—Speech Prefix Padding(ミリ秒)です。既定値:500、範囲:0-5000
silence_duration_msinteger—無音検出時間(ミリ秒)です。既定値:1000、範囲:100-10000
ツール選択パラメーター2個のフィールド
フィールド型必須説明選択肢または例
tool_choicestring—ツール選択方法です。選択肢:auto, none, required
toolsarray—利用可能なツール一覧です。選択肢:[{type, name, description, parameters}]
モデル設定パラメーター4個のフィールド
フィールド型必須説明選択肢または例
temperaturenumber—Sampling Temperature です。範囲/選択肢:0.0-2.0;既定値:1.0
max_output_tokensinteger または string—最大出力長です。範囲/選択肢:1-4096/"inf";既定値:"inf"
modalitiesstring[]—レスポンスのモダリティです。範囲/選択肢:["text", "audio"];既定値:["text"]
voicestring—Voice です。範囲/選択肢:alloy, echo, shimmer;既定値:alloy
イベント共通パラメーター3個のフィールド
フィールド型必須説明選択肢または例
event_idstringはいイベントの一意な識別子です。例:event_123
typestringはいイベント種別です。例:session.update
timestampintegerいいえイベント発生時刻(ミリ秒)です。例:1677649363000
セッション状態パラメーター3個のフィールド
フィールド型必須説明選択肢または例
statusstring—セッション状態です。選択肢:active, ended, error
errorobject—エラー情報です。選択肢:{"type": "error_type", "message": "error message"}
metadataobject—セッションメタデータです。選択肢:{"client_id": "web", "session_type": "chat"}
会話項目状態パラメーター3個のフィールド
フィールド型必須説明選択肢または例
statusstring—会話項目の状態です。選択肢:completed, in_progress, incomplete
rolestring—送信者の Role です。選択肢:user, assistant, system
typestring—会話項目の種類です。選択肢:message, function_call, function_call_output
コンテンツ種別パラメーター3個のフィールド
フィールド型必須説明選択肢または例
typestring—コンテンツ種別です。選択肢:text, audio, transcript
formatstring—コンテンツ形式です。選択肢:plain, markdown, html
encodingstring—エンコード方式です。選択肢:utf-8, base64
レスポンス状態パラメーター3個のフィールド
フィールド型必須説明選択肢または例
statusstring—レスポンス状態です。選択肢:completed, cancelled, failed, incomplete
status_detailsobject—状態の詳細です。選択肢:{"reason": "user_cancelled"}
usageobject—Usage 情報です。選択肢:{"total_tokens": 50, "input_tokens": 20, "output_tokens": 30}
音声文字起こしパラメーター4個のフィールド
フィールド型必須説明選択肢または例
enabledboolean—文字起こしを有効にするかどうかです。例:true
modelstring—文字起こしモデルです。例:whisper-1
languagestring—文字起こし言語です。例:en, zh, auto
promptstring—文字起こし用プロンプトです。例:"Transcript of a conversation"
音声ストリームパラメーター3個のフィールド
フィールド型必須説明選択肢または例
chunk_sizeinteger—音声チャンクサイズ(Byte)です。選択肢:1024, 2048, 4096
latencystring—遅延モードです。選択肢:low, balanced, high
compressionstring—圧縮方式です。選択肢:none, opus, mp3
WebRTC 設定パラメーター3個のフィールド
フィールド型必須説明選択肢または例
ice_serversarray—ICE サーバー一覧です。既定値:[{"urls": "stun:stun.l.google.com:19302"}]
audio_constraintsobject—音声制約です。既定値:{"echoCancellation": true}
connection_timeoutinteger—接続タイムアウト(ミリ秒)です。既定値:30000

エラー処理と復旧

Realtime のエラーは、主に接続、認証、音声、セッションの 4 種類に分けられます。

種類主な原因推奨対応
接続エラーネットワーク切断、ハンドシェイク失敗、無効な接続設定WSS URL、ネットワーク、ハンドシェイクリクエストを確認し、回数を制限して再接続します
認証エラー無効な API キー、期限切れの一時トークン、API アドレスと一致しない認証情報認証情報を更新し、リクエストで使用する API アドレスと API キーが一致していることを確認します
音声エラーデバイス権限、未対応形式、エンコードの不一致デバイス権限、サンプルレート、エンコードを確認し、音声経路を再確立します
セッションエラーセッションタイムアウト、同時実行数制限、イベント状態の不整合エラーイベントを保存して新しいセッションを作成し、必要に応じて非 Realtime API へフォールバックします

復旧方法には、自動再接続、セッション復旧、回数を制限した再試行、機能のフォールバックがあります。エラー発生時は、再送を判断する前に error イベントを確認し、event_id、error.type、error.code、error.message、関連イベント情報を保存してください。