使用 GPT 实时 API 处理语音和音频

Azure OpenAI 的 GPT 实时 API 隶属于 GPT-4o 模型家族，专为实现低延迟的“语音输入、语音输出”对话式交互而设计。你可以通过 WebRTC 或 WebSocket 连接此 API，实时发送音频输入并接收模型的音频响应。

本文将重点介绍如何通过 WebSocket 使用 GPT 实时 API。WebSocket 适用于服务器到服务器的场景，或对延迟要求不那么极致的客户端应用。

提示对于网页或移动应用等客户端实时音频流场景，我们强烈推荐使用 WebRTC。WebRTC 专为低延迟实时音频传输设计，是大多数用例的最佳选择。

支持的模型

GPT 实时模型已在全球范围部署。

gpt-4o-realtime-preview (版本 2024-12-17)
gpt-4o-mini-realtime-preview (版本 2024-12-17)
gpt-realtime (版本 2025-08-28)

更多模型和版本信息，请参阅相关官方文档。

API 版本支持

实时 API 的支持始于 2024-10-01-preview 版本（现已停用）。请使用 2025-08-28 或更新版本以获取最新的 API 功能。

准备工作

在开始之前，请确保你已准备好以下环境和配置：

Azure 订阅：你可以免费创建一个。
Node.js：需要 LTS 或 ESM 版本。
Azure OpenAI 资源：在支持的区域创建一个 Azure OpenAI 资源，并部署一个 gpt-realtime 模型。
身份验证：推荐使用 Microsoft Entra ID 进行无密钥身份验证。为此，你需要：
1. 安装 Azure CLI。
2. 为你的用户账户分配 认知服务用户 (Cognitive Services User) 角色。你可以在 Azure 门户的“访问控制 (IAM)” > “添加角色分配”中完成此操作。

部署模型

你可以通过 Azure AI Foundry 门户部署 gpt-realtime 模型。

登录 Azure AI Foundry 门户，创建或选择你的项目。
在左侧导航栏的“我的资产”下，选择 模型 + 终结点 (Models + endpoints)。
点击 + 部署模型 (+ Deploy model) > 部署基础模型 (Deploy base model)。
搜索并选择 gpt-realtime 模型，然后点击 确认 (Confirm)。
检查部署详情，点击 部署 (Deploy)，并按照向导完成后续步骤。

部署完成后，你就可以通过 Azure AI Foundry 的音频演练场 (Audio playground) 或实时 API 与模型进行交互。

在音频演练场中测试

你可以直接在 Azure AI Foundry 中与已部署的 gpt-realtime 模型进行语音对话测试。

进入你的项目，在左侧导航栏选择 演练场 (Playgrounds)。
选择 音频演练场 (Audio playground) > 尝试音频演练场 (Try the Audio playground)。

注意：聊天演练场 (Chat playground) 不支持 gpt-realtime 模型。
在 部署 (Deployment) 下拉菜单中，选择你刚刚部署的 gpt-realtime 模型。
（可选）在 为模型提供指令和上下文 (Give the model instructions and context) 文本框中编辑系统提示，定义助手的性格、回答范围和格式等。
（可选）调整其他设置，如阈值、前缀填充和静音时长。
点击 开始收听 (Start listening) 启动会话，然后对着麦克风说话即可开始聊天。你可以随时通过说话打断模型。
点击 停止收听 (Stop listening) 结束会话。

快速入门：使用 WebSocket 和 Node.js

本节将指导你如何使用 Node.js 通过 WebSocket 连接实时 API。

1. 初始化项目

首先，创建一个新的项目文件夹并初始化 Node.js 项目。

mkdir realtime-audio-quickstart && cd realtime-audio-quickstart
npm init -y

接着，安装所需的 OpenAI 客户端库和 Azure 身份验证库。

# 安装 OpenAI 库
npm install openai

# 安装用于 Microsoft Entra ID 无密钥身份验证的库
npm install @azure/identity

2. 获取资源信息

你的应用程序需要以下信息来连接 Azure OpenAI 资源。请将它们设置为环境变量，以确保安全。

方法一：Microsoft Entra ID（推荐）

环境变量	说明
`AZURE_OPENAI_ENDPOINT`	你的 Azure OpenAI 资源的终结点。可在 Azure 门户的“密钥和终结点”部分找到。
`AZURE_OPENAI_DEPLOYMENT_NAME`	你部署 `gpt-realtime` 模型时设置的自定义名称。可在“资源管理” > “模型部署”下找到。
`OPENAI_API_VERSION`	API 版本，例如 `2025-08-28`。

注意：使用此方法时，请确保不要设置 AZURE_OPENAI_API_KEY 环境变量。

方法二：API 密钥

环境变量	说明
`AZURE_OPENAI_ENDPOINT`	你的 Azure OpenAI 资源的终结点。
`AZURE_OPENAI_API_KEY`	你的 API 密钥（KEY1 或 KEY2）。
`AZURE_OPENAI_DEPLOYMENT_NAME`	你的模型部署名称。
`OPENAI_API_VERSION`	API 版本，例如 `2025-08-28`。

重要提示：请谨慎使用 API 密钥。不要将其硬编码在代码中或公开发布。推荐使用 Azure Key Vault 等服务安全地存储和管理密钥。

3. 编写代码（文本输入，音频输出）

以下示例演示了如何发送文本指令，并接收模型的文本和音频流式响应。

使用 Microsoft Entra ID 认证

创建一个名为 index.js 的文件，并添加以下代码：

import { OpenAIRealtimeWS } from "openai/beta/realtime/ws";
import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";

async function main() {
  // 从环境变量读取或直接修改以下值
  const endpoint = process.env.AZURE_OPENAI_ENDPOINT || "在此处填入你的终结点";
  const deploymentName = process.env.AZURE_OPENAI_DEPLOYMENT_NAME || "gpt-realtime";
  const apiVersion = process.env.OPENAI_API_VERSION || "2025-08-28";

  // 使用无密钥身份验证
  const credential = new DefaultAzureCredential();
  const scope = "https://cognitiveservices.azure.com/.default";
  const azureADTokenProvider = getBearerTokenProvider(credential, scope);

  const azureOpenAIClient = new AzureOpenAI({
    azureADTokenProvider,
    apiVersion: apiVersion,
    deployment: deploymentName,
    endpoint: endpoint,
  });

  const realtimeClient = await OpenAIRealtimeWS.azure(azureOpenAIClient);

  realtimeClient.socket.on("open", () => {
    console.log("连接已建立！");
    // 更新会话，指定输出模式为文本和音频
    realtimeClient.send({
      type: "session.update",
      session: {
        output_modalities: ["text", "audio"],
        model: "gpt-realtime",
      },
    });
    // 创建一个对话项，发送用户输入
    realtimeClient.send({
      type: "conversation.item.create",
      item: {
        type: "message",
        role: "user",
        content: [{ type: "input_text", text: "请为用户提供帮助" }],
      },
    });
    // 请求模型生成响应
    realtimeClient.send({ type: "response.create" });
  });

  // 监听并处理各种事件
  realtimeClient.on("error", (err) => {
    console.error("发生错误:", err);
  });

  realtimeClient.on("session.created", (event) => {
    console.log("会话已创建:", event.session);
    console.log();
  });

  realtimeClient.on("response.output_text.delta", (event) => {
    process.stdout.write(event.delta);
  });

  realtimeClient.on("response.output_audio.delta", (event) => {
    const buffer = Buffer.from(event.delta, "base64");
    console.log(`收到 ${buffer.length} 字节的音频数据。`);
  });

  realtimeClient.on("response.output_audio_transcript.delta", (event) => {
    console.log(`收到音频转录文本: ${event.delta}`);
  });

  realtimeClient.on("response.text.done", () => console.log());

  realtimeClient.on("response.done", () => realtimeClient.close());

  realtimeClient.socket.on("close", () => console.log("\n连接已关闭！"));
}

main().catch((err) => {
  console.error("示例运行时遇到错误:", err);
});

export { main };

使用 API 密钥认证

如果你选择使用 API 密钥，请将 index.js 文件内容替换为以下代码：

import { OpenAIRealtimeWS } from "openai/beta/realtime/ws";
import { AzureOpenAI } from "openai";

async function main() {
  // 从环境变量读取或直接修改以下值
  const endpoint = process.env.AZURE_OPENAI_ENDPOINT || "在此处填入你的终结点";
  const apiKey = process.env.AZURE_OPENAI_API_KEY || "在此处填入你的API密钥";
  const deploymentName = process.env.AZURE_OPENAI_DEPLOYMENT_NAME || "gpt-realtime";
  const apiVersion = process.env.OPENAI_API_VERSION || "2025-08-28";

  const azureOpenAIClient = new AzureOpenAI({
    apiKey: apiKey,
    apiVersion: apiVersion,
    deployment: deploymentName,
    endpoint: endpoint,
  });

  const realtimeClient = await OpenAIRealtimeWS.azure(azureOpenAIClient);

  realtimeClient.socket.on("open", () => {
    console.log("连接已建立！");
    // 更新会话，指定输出模式为文本和音频
    realtimeClient.send({
      type: "session.update",
      session: {
        output_modalities: ["text", "audio"],
        model: "gpt-realtime",
      },
    });
    // 创建一个对话项，发送用户输入
    realtimeClient.send({
      type: "conversation.item.create",
      item: {
        type: "message",
        role: "user",
        content: [{ type: "input_text", text: "请为用户提供帮助" }],
      },
    });
    // 请求模型生成响应
    realtimeClient.send({ type: "response.create" });
  });

  // 事件监听部分与上一个示例相同
  realtimeClient.on("error", (err) => {
    console.error("发生错误:", err);
  });

  realtimeClient.on("session.created", (event) => {
    console.log("会话已创建:", event.session);
    console.log();
  });

  realtimeClient.on("response.output_text.delta", (event) => {
    process.stdout.write(event.delta);
  });

  realtimeClient.on("response.output_audio.delta", (event) => {
    const buffer = Buffer.from(event.delta, "base64");
    console.log(`收到 ${buffer.length} 字节的音频数据。`);
  });

  realtimeClient.on("response.output_audio_transcript.delta", (event) => {
    console.log(`收到音频转录文本: ${event.delta}`);
  });

  realtimeClient.on("response.text.done", () => console.log());

  realtimeClient.on("response.done", () => realtimeClient.close());

  realtimeClient.socket.on("close", () => console.log("\n连接已关闭！"));
}

main().catch((err) => {
  console.error("示例运行时遇到错误:", err);
});

4. 运行应用

在终端中执行以下命令来运行你的代码。

# 如果使用 Microsoft Entra ID 认证，请先登录 Azure
az login

# 运行 JavaScript 文件
node index.js

程序将连接到实时 API，发送文本消息，并打印出收到的流式文本和音频数据信息。

👉 如果你需要 ChatGPT 代充 / Claude / Claude Code / 镜像 / 中转 API：

购买 / 了解更多：ai4.plus
备用入口：kk4099.com

支持的模型#

API 版本支持#

准备工作#

部署模型#

在音频演练场中测试#

快速入门：使用 WebSocket 和 Node.js#

1. 初始化项目#

2. 获取资源信息#

方法一：Microsoft Entra ID（推荐）#

方法二：API 密钥#

3. 编写代码（文本输入，音频输出）#

使用 Microsoft Entra ID 认证#

使用 API 密钥认证#

4. 运行应用#