跳到主要内容

Realtime API

AISIX AI 网关在 GET /v1/realtime 通过 WebSocket 转发 OpenAI Realtime API。网关会在连接建立前完成客户端认证、模型别名解析、访问控制和限流策略检查，然后在客户端与服务提供方之间双向转发事件。

本指南将演示如何通过网关连接 Realtime 客户端，并说明该端点的关键会话行为。

前提条件​

开始前请准备：

  • 一个可处理代理请求的 AISIX 网关。
  • 一个可访问目标模型别名的调用方 API Key。
  • 一个由支持 OpenAI Realtime 协议的服务提供方支持的模型别名。

目前支持兼容 OpenAI 的服务提供方（适配器为 openai，包括自定义 api_base 部署）和 Azure OpenAI（适配器为 azure-openai，使用 /openai/realtime 和 api-key 认证）。Gemini Live 和 Bedrock 使用不同的实时事件协议，暂不通过该端点提供。

连接客户端​

通过 model 查询参数选择模型。服务端客户端使用标准请求头认证：

import WebSocket from "ws";

const ws = new WebSocket(
  "ws://127.0.0.1:3000/v1/realtime?model=realtime-prod",
  { headers: { Authorization: "Bearer YOUR_CALLER_API_KEY" } },
);

浏览器客户端无法设置 WebSocket 请求头。可以像 OpenAI 浏览器示例一样，把调用方 API Key 作为 subprotocol 项传入，网关会回显 realtime subprotocol：

const ws = new WebSocket(
  "wss://gateway.example.com/v1/realtime?model=realtime-prod",
  [
    "realtime",
    "openai-insecure-api-key.YOUR_CALLER_API_KEY",
  ],
);

连接建立后，可以像直接连接服务提供方一样收发 Realtime 事件，例如 session.update、音频 buffer、response.create 和服务端事件流。

认证与策略​

认证、模型访问检查、客户端 IP 限制、预算和限流会在 WebSocket upgrade 完成前执行。任何检查失败都会在 HTTP 握手阶段被拒绝（401、403 或 429），客户端会看到连接建立失败。

会话期间，已配置的安全护栏会扫描双向文本事件。被阻断的事件会产生 OpenAI 风格的 error 事件，随后连接关闭。

用量跟踪​

网关会从服务提供方的 response.done 事件中提取用量信息；转录会话还会从转录完成事件中提取用量。每个会话会记录一个聚合用量事件，包括缓存 Token 数。会话总 Token 会计入基于 Token 的限流。

会话限制​

如果模型配置了 stream_timeout，该值会作为事件之间的空闲上限；超过该时间没有事件的会话会因超时关闭。未配置时，网关不施加额外会话时长限制。上游连接失败会以 1011 关闭会话，并计入模型冷却。

下一步​

你已经通过网关连接了 Realtime 客户端。接下来可阅读语音与音频，了解非实时音频端点。