跳转到主要内容
Realtime API 允许你通过 WebSocket 连接与模型进行低延迟、双向的语音和文本对话。无需发送离散的 HTTP 请求，你打开一个持久连接，双向交换事件消息——发送音频或文本输入，接收流式生成的音频或文本响应。 OpenOpen8 的 Realtime 端点兼容 OpenAI Realtime API 格式，也支持 Azure OpenAI Realtime。连接前需要配置一个支持 Realtime 的渠道（OpenAI 或 Azure OpenAI）。
Realtime 需要配置支持实时对话的服务商渠道（OpenAI 或 Azure OpenAI）。如果 WebSocket 连接被拒绝，请联系你的 OpenOpen8 管理员。

​
连接

端点： GET /v1/realtime 将 HTTP GET 请求升级为 WebSocket 连接。可通过查询参数或 WebSocket 握手中的 Authorization 头传入 token。 
ws://openopen8.ai/v1/realtime
TLS 加密实例： 
wss://openopen8.ai/v1/realtime

​
认证

通过以下方式传入 token：
  • 查询参数： ?token=YOUR_TOKEN
  • Authorization 头： Authorization: Bearer YOUR_TOKEN（在 HTTP 升级握手时设置）

​
事件类型

连接后，双方交换 JSON 事件消息。每条消息包含 type 字段标识其用途。以下是核心事件类型。

​
客户端 → 服务端

事件类型说明
session.update配置会话参数，如语音、音频格式、工具和指令。
input_audio_buffer.append向模型的输入缓冲区发送 base64 编码的音频数据。
conversation.item.create向对话中添加一条文本消息。
response.create提示模型基于当前对话和缓冲区生成响应。

​
服务端 → 客户端

事件类型说明
session.created连接后立即发送，确认会话已就绪。
session.updated确认 session.update 已生效。
response.audio.delta模型响应中的一块 base64 编码音频。
response.audio_transcript.delta模型音频输出的文本转录片段。
response.function_call_arguments.delta流式 function calling 参数（模型调用工具时）。
response.function_call_arguments.donefunction calling 参数发送完成。
response.done模型完成响应生成。包含用量信息。
conversation.item.created确认对话项已添加。
error发生错误。包含错误对象及消息和代码。

​
会话配置

连接后，发送 session.update 事件配置会话：
​
modalities
string[]
启用的交互模式。例如 ["text", "audio"]。
​
instructions
string
系统级指令，引导模型在整个会话中的行为。
​
voice
string
音频输出使用的语音。例如 alloy、echo、nova 或 shimmer。
​
input_audio_format
string
你发送的音频格式。例如 pcm16、g711_ulaw 或 g711_alaw。
​
output_audio_format
string
模型返回的音频格式。例如 pcm16。
​
input_audio_transcription
object
音频输入转录配置。
​
turn_detection
object | null
控制服务端如何检测音频输入的轮次结束。设为 null 禁用自动检测，手动管理。
​
tools
object[]
会话中模型可用的工具列表，遵循 OpenAI function calling schema。
​
tool_choice
string
控制模型何时使用工具。auto、none 或指定工具名。
​
temperature
number
模型的采样温度。默认 0.8。

​
用量统计

模型完成响应后，response.done 事件包含 usage 对象：
​
total_tokens
integer
此轮响应消耗的总 token 数。
​
input_tokens
integer
输入中的 token 数（音频 + 文本）。
​
output_tokens
integer
模型输出中的 token 数（音频 + 文本）。
​
input_token_details
object
输入 token 类型明细（如缓存、音频）。
​
output_token_details
object
输出 token 类型明细（如音频、文本）。

​
示例

以下 JavaScript 示例连接 Realtime 端点、配置会话并记录收到的事件。
javascript
const ws = new WebSocket(
  "wss://openopen8.ai/v1/realtime?token=YOUR_TOKEN"
);

ws.addEventListener("open", () => {
  // Configure the session
  ws.send(
    JSON.stringify({
      type: "session.update",
      session: {
        modalities: ["text", "audio"],
        instructions: "You are a helpful assistant. Respond concisely.",
        voice: "alloy",
        input_audio_format: "pcm16",
        output_audio_format: "pcm16",
        temperature: 0.8,
      },
    })
  );

  // Send a text message
  ws.send(
    JSON.stringify({
      type: "conversation.item.create",
      item: {
        type: "message",
        role: "user",
        content: [{ type: "input_text", text: "Hello, how are you?" }],
      },
    })
  );

  // Ask the model to respond
  ws.send(JSON.stringify({ type: "response.create" }));
});

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.type, msg);
});

ws.addEventListener("error", (err) => {
  console.error("WebSocket error", err);
});