> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime 实时对话

> WebSocket 双向语音 / 文本流接口

OpenAI Realtime API 提供双向、低延迟的语音 / 文本流,适用于语音助手 / 实时会议总结等场景。

<Note>OpenAI 官方支持 **WebRTC / WebSocket / SIP** 三种接入方式,并提供 `gpt-realtime-2`、`gpt-realtime-1.5` 等新一代实时模型。OpenPAI 网关当前以 **WebSocket** 为主,其他传输方式与模型是否开放以 **控制台 / 公告** 为准。</Note>

## 连接

```
wss://openp.ai/v1/realtime?model=gpt-realtime-2
```

握手时通过 **子协议** 或 **Header** 传递鉴权:

| 方式                  | 示例                                                                           |
| ------------------- | ---------------------------------------------------------------------------- |
| Header(Node / curl) | `Authorization: Bearer sk-XXXXXXXXXXXX` + `OpenAI-Beta: realtime=v1`         |
| 浏览器子协议              | `["realtime", "openai-insecure-api-key.sk-XXXX", "openai-beta.realtime-v1"]` |

<Warning>浏览器子协议方式会把密钥放在客户端,**仅用于 demo**。生产请通过自己的后端创建临时 token。</Warning>

## 创建临时 Token

```bash theme={null}
curl https://openp.ai/v1/realtime/sessions \
  -H "Authorization: Bearer $OPENPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-realtime-2",
    "voice": "alloy"
  }'
```

返回中的 `client_secret.value` 是短期 token,可安全发送到浏览器作为子协议。

## 事件协议

WebSocket 上双向收发 JSON 事件,关键事件:

| 客户端发送                                            | 服务端回复                                                                                 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `session.update` —— 设置 instructions / voice / 工具 | `session.created` / `session.updated`                                                 |
| `input_audio_buffer.append` —— PCM16 音频追加        | `input_audio_buffer.committed`                                                        |
| `input_audio_buffer.commit` —— 提交一段音频            | `conversation.item.created`                                                           |
| `conversation.item.create` —— 追加文本消息             | `conversation.item.created`                                                           |
| `response.create` —— 请求生成响应                      | `response.created` / `response.audio.delta` / `response.text.delta` / `response.done` |

## 简化示例(Node.js)

```ts theme={null}
import WebSocket from "ws";

const ws = new WebSocket(
  "wss://openp.ai/v1/realtime?model=gpt-realtime-2",
  { headers: {
    "Authorization": `Bearer ${process.env.OPENPAI_API_KEY}`,
    "OpenAI-Beta": "realtime=v1",
  }}
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "session.update",
    session: { instructions: "你是中文助手", voice: "alloy" }
  }));

  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: { type: "message", role: "user", content: [{type:"input_text", text:"hi"}]}
  }));

  ws.send(JSON.stringify({ type: "response.create" }));
});

ws.on("message", (data) => {
  const evt = JSON.parse(data.toString());
  if (evt.type === "response.text.delta") process.stdout.write(evt.delta);
});
```

## 音频格式

* **输入**:PCM 16-bit、24kHz、单声道,base64 编码。
* **输出**:同样 PCM 16-bit / 24kHz。

可借助 `webrtc-adapter`、`MediaRecorder`、`ffmpeg` 等工具转换。

## 工具调用

`session.update` 中可声明 `tools`,模型在生成过程中可能产生 `response.function_call_arguments.delta` 事件,
你需要执行工具并把结果通过 `conversation.item.create`(`type: function_call_output`)回传。

## 计费

* **音频输入 / 输出 token** 与 **文本 token** 分别计费,价格高于普通 chat。
* 连接保持期间不计费,但若长时间空闲建议主动关闭。

详见 [模型定价](/models/openai)。