OpenAI Realtime
Realtime WebSocket 接続を通じて、リアルタイムのテキスト、音声、関数呼び出しを処理します。
OpenAI Realtime は、持続的な接続と双方向イベントを使用して、リアルタイムのテキスト、音声、関数呼び出しを処理します。クライアントはセッション、音声バッファ、会話項目、レスポンス制御の各イベントを送信し、サーバーはセッション状態、文字起こし、テキスト、音声、関数引数、エラーイベントを継続的に返します。
このページでは、主に WebSocket 接続を扱います。接続時に、MODEL_ID を現在のアカウントで利用でき、Realtime に対応するモデル ID に置き換えてください。
主な用途には、リアルタイム音声会話、会議のライブ文字起こし、音声アシスタント、リアルタイム翻訳、音声認識、対話型コーディング、サーバー側のリアルタイム連携があります。1 つの接続でテキストと音声の両方を送受信でき、イベントによって VAD、関数呼び出し、状態更新を制御します。
wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID認証と接続
WebSocket 認証
サーバーアプリケーションは、Bearer API キーを使用して WSS 接続を確立し、ハンドシェイクリクエストに Realtime Beta Header を含めます。
| 項目 | 値 |
|---|---|
| 接続 URL | wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID |
| Authorization | Bearer your-api-key |
| OpenAI-Beta | realtime=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 イベントを継続的に返します。
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 を使用する基本的な接続構造を示します。
WebRTC の接続 URL は https://api.agtcloud.cn/v1/realtime?model=MODEL_ID です。クライアントは一時トークンを使用して application/sdp を送信します。Data Channel の名前は oai-events で、イベントには JSON を使用します。入力音声は addTrack() で送信し、出力音声は ontrack で受信します。
ブラウザクライアントと SDP 交換
async function init() {
const tokenResponse = await fetch('/session');
const data = await tokenResponse.json();
const ephemeralKey = data.client_secret.value;
const pc = new RTCPeerConnection();
const audioElement = document.createElement('audio');
audioElement.autoplay = true;
pc.ontrack = (event) => {
audioElement.srcObject = event.streams[0];
};
const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
pc.addTrack(mediaStream.getTracks()[0]);
const dataChannel = pc.createDataChannel('oai-events');
dataChannel.addEventListener('message', (event) => {
console.log(JSON.parse(event.data));
});
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
const response = await fetch(
'https://api.agtcloud.cn/v1/realtime?model=MODEL_ID',
{
method: 'POST',
body: offer.sdp,
headers: {
Authorization: `Bearer ${ephemeralKey}`,
'Content-Type': 'application/sdp',
},
},
);
await pc.setRemoteDescription({
type: 'answer',
sdp: await response.text(),
});
}
init();サーバーで一時トークンを作成
import express from 'express';
const app = express();
app.get('/session', async (_request, response) => {
const result = await fetch('https://api.agtcloud.cn/v1/realtime/sessions', {
method: 'POST',
headers: {
Authorization: 'Bearer your-api-key',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'MODEL_ID',
voice: 'verse',
}),
});
response.send(await result.json());
});
app.listen(3000);Data Channel イベントの送受信
const dataChannel = pc.createDataChannel('oai-events');
dataChannel.addEventListener('message', (event) => {
const realtimeEvent = JSON.parse(event.data);
console.log(realtimeEvent);
});
dataChannel.send(JSON.stringify({
type: 'response.create',
response: {
modalities: ['text'],
instructions: 'コードを題材に俳句を作ってください',
},
}));ブラウザ互換ランタイム向けの標準 WebSocket 例
Deno や Cloudflare Workers などのブラウザ互換ランタイムでは、サブプロトコルを通じて認証情報を渡せます。使用前に、現在のランタイムとノードがこの方式に対応していることを確認してください。通常のブラウザページに長期 API キーを配置しないでください。
const ws = new WebSocket(
'wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID',
[
'realtime',
'openai-insecure-api-key.your-api-key',
'openai-organization.ORGANIZATION_ID',
'openai-project.PROJECT_ID',
'openai-beta.realtime-v1',
],
);
ws.addEventListener('open', () => {
console.log('サーバーに接続しました。');
});
ws.addEventListener('message', (event) => {
console.log(JSON.parse(event.data));
});セッション、音声、会話
Realtime は、テキストのみ、音声のみ、テキストと音声を組み合わせた会話に対応します。セッション設定には、入出力音声形式、Voice、Temperature、最大出力長、ツール、VAD 設定を含められます。
- 入出力音声形式:
pcm16、g711_ulaw、g711_alaw。 - Voice の例:
alloy、echo、shimmer。 - VAD 設定には、検出しきい値、Prefix Padding、無音時間が含まれます。
- セッション、会話項目、Content Part、レスポンスイベントによって会話が進行します。
各イベントのフィールドは、以下のイベントブラウザで確認してください。共通パラメーターと値の範囲は「共通型」にまとめています。
イベントリファレンス
イベントを選択すると、フィールド定義と JSON 例を確認できます。イベント方向の切り替え、カテゴリーフィルター、イベント名検索も利用できます。
session.update
セッションの既定設定を更新します。
| フィールド | 型 | 必須 | 説明 | 例 |
|---|---|---|---|---|
event_id | string | いいえ | クライアントが生成したイベント識別子です。 | event_123 |
type | string | いいえ | イベント種別です。 | session.update |
modalities | string[] | いいえ | モデルがレスポンスで使用できるモダリティです。 | ["text", "audio"] |
instructions | string | いいえ | モデル呼び出し前に適用するシステム指示です。 | "簡潔かつ正確に回答してください。" |
voice | string | いいえ | モデルが使用する Voice です。 | alloy、echo、shimmer |
input_audio_format | string | いいえ | 入力音声形式です。 | pcm16、g711_ulaw、g711_alaw |
output_audio_format | string | いいえ | 出力音声形式です。 | pcm16、g711_ulaw、g711_alaw |
input_audio_transcription.model | string | いいえ | 文字起こしに使用するモデルです。 | whisper-1 |
turn_detection.type | string | いいえ | 音声検出の種類です。 | server_vad |
turn_detection.threshold | number | いいえ | VAD の検出しきい値(0.0~1.0)です。 | 0.8 |
turn_detection.prefix_padding_ms | integer | いいえ | 発話開始前に含める音声時間です。 | 500 |
turn_detection.silence_duration_ms | integer | いいえ | 発話終了の検出に使用する無音時間です。 | 1000 |
tools | array | いいえ | モデルが利用できるツールの一覧です。 | [] |
tool_choice | string | いいえ | モデルがツールを選択する方法です。 | auto/none/required |
temperature | number | いいえ | モデルの Sampling Temperature です。 | 0.8 |
max_output_tokens | string または integer | いいえ | 1 回のレスポンスにおける最大 Token 数です。 | "inf"/4096 |
{
"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個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
name | string | はい | Rate Limit 名です。 | 例:requests_per_min |
limit | integer | はい | 制限値です。 | 例:60 |
remaining | integer | はい | 残りの利用可能量です。 | 例:45 |
reset_seconds | integer | はい | リセットまでの秒数です。 | 例:35 |
関数呼び出しパラメーター4個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
type | string | はい | 関数の種類です。 | 例:function |
name | string | はい | 関数名です。 | 例:get_weather |
description | string | いいえ | 関数の説明です。 | 例:Get the current weather |
parameters | object | はい | 関数パラメーターの定義です。 | 例:{"type": "object", "properties": {...}} |
音声形式パラメーター4個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
sample_rate | integer | — | サンプルレートです。 | 選択肢:8000, 16000, 24000, 44100, 48000 |
channels | integer | — | チャンネル数です。 | 選択肢:1 (モノラル), 2 (ステレオ) |
bits_per_sample | integer | — | 量子化 Bit 数です。 | 選択肢:16 (pcm16), 8 (g711) |
encoding | string | — | エンコード方式です。 | 選択肢:pcm16, g711_ulaw, g711_alaw |
音声検出パラメーター3個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
threshold | number | — | VAD の検出しきい値です。 | 既定値:0.5、範囲:0.0-1.0 |
prefix_padding_ms | integer | — | Speech Prefix Padding(ミリ秒)です。 | 既定値:500、範囲:0-5000 |
silence_duration_ms | integer | — | 無音検出時間(ミリ秒)です。 | 既定値:1000、範囲:100-10000 |
ツール選択パラメーター2個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
tool_choice | string | — | ツール選択方法です。 | 選択肢:auto, none, required |
tools | array | — | 利用可能なツール一覧です。 | 選択肢:[{type, name, description, parameters}] |
モデル設定パラメーター4個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
temperature | number | — | Sampling Temperature です。 | 範囲/選択肢:0.0-2.0;既定値:1.0 |
max_output_tokens | integer または string | — | 最大出力長です。 | 範囲/選択肢:1-4096/"inf";既定値:"inf" |
modalities | string[] | — | レスポンスのモダリティです。 | 範囲/選択肢:["text", "audio"];既定値:["text"] |
voice | string | — | Voice です。 | 範囲/選択肢:alloy, echo, shimmer;既定値:alloy |
イベント共通パラメーター3個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
event_id | string | はい | イベントの一意な識別子です。 | 例:event_123 |
type | string | はい | イベント種別です。 | 例:session.update |
timestamp | integer | いいえ | イベント発生時刻(ミリ秒)です。 | 例:1677649363000 |
セッション状態パラメーター3個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
status | string | — | セッション状態です。 | 選択肢:active, ended, error |
error | object | — | エラー情報です。 | 選択肢:{"type": "error_type", "message": "error message"} |
metadata | object | — | セッションメタデータです。 | 選択肢:{"client_id": "web", "session_type": "chat"} |
会話項目状態パラメーター3個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
status | string | — | 会話項目の状態です。 | 選択肢:completed, in_progress, incomplete |
role | string | — | 送信者の Role です。 | 選択肢:user, assistant, system |
type | string | — | 会話項目の種類です。 | 選択肢:message, function_call, function_call_output |
コンテンツ種別パラメーター3個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
type | string | — | コンテンツ種別です。 | 選択肢:text, audio, transcript |
format | string | — | コンテンツ形式です。 | 選択肢:plain, markdown, html |
encoding | string | — | エンコード方式です。 | 選択肢:utf-8, base64 |
レスポンス状態パラメーター3個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
status | string | — | レスポンス状態です。 | 選択肢:completed, cancelled, failed, incomplete |
status_details | object | — | 状態の詳細です。 | 選択肢:{"reason": "user_cancelled"} |
usage | object | — | Usage 情報です。 | 選択肢:{"total_tokens": 50, "input_tokens": 20, "output_tokens": 30} |
音声文字起こしパラメーター4個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
enabled | boolean | — | 文字起こしを有効にするかどうかです。 | 例:true |
model | string | — | 文字起こしモデルです。 | 例:whisper-1 |
language | string | — | 文字起こし言語です。 | 例:en, zh, auto |
prompt | string | — | 文字起こし用プロンプトです。 | 例:"Transcript of a conversation" |
音声ストリームパラメーター3個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
chunk_size | integer | — | 音声チャンクサイズ(Byte)です。 | 選択肢:1024, 2048, 4096 |
latency | string | — | 遅延モードです。 | 選択肢:low, balanced, high |
compression | string | — | 圧縮方式です。 | 選択肢:none, opus, mp3 |
WebRTC 設定パラメーター3個のフィールド
| フィールド | 型 | 必須 | 説明 | 選択肢または例 |
|---|---|---|---|---|
ice_servers | array | — | ICE サーバー一覧です。 | 既定値:[{"urls": "stun:stun.l.google.com:19302"}] |
audio_constraints | object | — | 音声制約です。 | 既定値:{"echoCancellation": true} |
connection_timeout | integer | — | 接続タイムアウト(ミリ秒)です。 | 既定値:30000 |
エラー処理と復旧
Realtime のエラーは、主に接続、認証、音声、セッションの 4 種類に分けられます。
| 種類 | 主な原因 | 推奨対応 |
|---|---|---|
| 接続エラー | ネットワーク切断、ハンドシェイク失敗、無効な接続設定 | WSS URL、ネットワーク、ハンドシェイクリクエストを確認し、回数を制限して再接続します |
| 認証エラー | 無効な API キー、期限切れの一時トークン、API アドレスと一致しない認証情報 | 認証情報を更新し、リクエストで使用する API アドレスと API キーが一致していることを確認します |
| 音声エラー | デバイス権限、未対応形式、エンコードの不一致 | デバイス権限、サンプルレート、エンコードを確認し、音声経路を再確立します |
| セッションエラー | セッションタイムアウト、同時実行数制限、イベント状態の不整合 | エラーイベントを保存して新しいセッションを作成し、必要に応じて非 Realtime API へフォールバックします |
復旧方法には、自動再接続、セッション復旧、回数を制限した再試行、機能のフォールバックがあります。エラー発生時は、再送を判断する前に error イベントを確認し、event_id、error.type、error.code、error.message、関連イベント情報を保存してください。