如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

实时翻译

实时翻译语音,流式输出译音和转写文本。

使用实时翻译,您可以将源音频流式传入专用翻译会话,在说话者讲话的同时接收译音和增量转写文本。这适用于现场口译、多语言通话、广播、会议、课堂和视频聊天室。

如果您的应用需要翻译说话者的语音,请使用 gpt-realtime-translate。如果您需要能回答问题、调用工具并管理对话的助手,请在标准 Realtime API 会话中使用 gpt-realtime-2.1。

翻译会话与语音智能体会话的区别

下表对比了实时翻译会话与语音智能体会话的架构。

语音智能体会话 翻译会话
连接到 /v1/realtime。 连接到 /v1/realtime/translations。
模型充当助手。 模型充当口译员。
按对话和响应的生命周期运行。 根据传入的音频持续流式输出翻译。
模型可以调用工具并生成助手回复。 模型输出译音和增量转写文本。
可以调用 response.create。 不调用 response.create。

音频流本身即可触发翻译。请持续追加音频,包括讲话间的静音片段,并在收到输出事件时进行处理。

选择传输方式

如果浏览器负责采集或播放音频,请使用 WebRTC。WebRTC 通过媒体轨道发送源音频,并通过远端音轨接收译音,因此您无需手动重采样或播放 PCM 音频块。

如果服务器已在接收原始音频,例如来自 Twilio Media Streams、SIP 媒体流、广播接入流或媒体处理进程的音频,请使用 WebSocket。使用 WebSocket 时,请发送经 base64 编码的 24 kHz PCM16 音频,并自行播放陆续返回的音频片段。

在浏览器中创建 WebRTC 会话

对于浏览器应用,请在服务器上创建短期有效的客户端密钥。请勿在浏览器中暴露您的标准 API 密钥。

创建翻译会话的客户端密钥
app.post("/session", async (req, res) => {
  const language = req.body.targetLanguage ?? "es";

  const response = await fetch(
    "https://api.openai.com/v1/realtime/translations/client_secrets",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
        "Content-Type": "application/json",
        "OpenAI-Safety-Identifier": "hashed-user-id",
      },
      body: JSON.stringify({
        session: {
          model: "gpt-realtime-translate",
          audio: {
            output: { language },
          },
        },
      }),
    }
  );

  res.status(response.status).json(await response.json());
});

在浏览器中采集音频,创建对等连接,然后将 SDP offer 通过 POST 请求发送到翻译通话端点。

在浏览器中建立翻译通话连接
const { value: clientSecret } = await fetch("/session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ targetLanguage: "es" }),
}).then((response) => response.json());

const sourceStream = await navigator.mediaDevices.getUserMedia({
  audio: true,
});

const pc = new RTCPeerConnection();
pc.addTrack(sourceStream.getAudioTracks()[0], sourceStream);

const translatedAudio = new Audio();
translatedAudio.autoplay = true;
pc.ontrack = ({ streams }) => {
  translatedAudio.srcObject = streams[0];
};

const events = pc.createDataChannel("oai-events");
events.onmessage = ({ data }) => {
  const event = JSON.parse(data);
  if (event.type === "session.output_transcript.delta") {
    subtitles.textContent += event.delta;
  }
};

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

const sdpResponse = await fetch(
  "https://api.openai.com/v1/realtime/translations/calls",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${clientSecret}`,
      "Content-Type": "application/sdp",
    },
    body: offer.sdp,
  }
);

if (!sdpResponse.ok) {
  throw new Error(await sdpResponse.text());
}

await pc.setRemoteDescription({
  type: "answer",
  sdp: await sdpResponse.text(),
});

创建 WebSocket 会话

连接到专用翻译端点,并在 URL 中指定模型。

运行此示例前,请安装 Node.js 的 ws 包。

连接到翻译会话
import WebSocket from "ws";

const ws = new WebSocket(
  "wss://api.openai.com/v1/realtime/translations?model=gpt-realtime-translate",
  {
    headers: {
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
      "OpenAI-Safety-Identifier": "hashed-user-id",
    },
  }
);

套接字打开后,配置目标语言。

配置目标语言
ws.on("open", () => {
  ws.send(
    JSON.stringify({
      type: "session.update",
      session: {
        audio: {
          output: {
            language: "es",
          },
        },
      },
    })
  );
});

然后持续追加音频。

追加源音频
ws.send(
  JSON.stringify({
    type: "session.input_audio_buffer.append",
    audio: base64Pcm16,
  })
);

监听译音和转写文本。

监听译音和转写文本
ws.on("message", (data) => {
  const event = JSON.parse(data.toString());

  if (event.type === "session.output_audio.delta") {
    playPcm16(event.delta);
  }

  if (event.type === "session.output_transcript.delta") {
    process.stdout.write(event.delta);
  }

  if (event.type === "session.input_transcript.delta") {
    updateSourceTranscript(event.delta);
  }
});

如果使用 Go,请在发送音频的同时并发运行 listen。它会在收到 session.closed 后关闭传输连接。

关闭 WebSocket 会话

源音频流结束时,请先发送 session.close 事件,再关闭 WebSocket。此事件会指示服务处理完剩余的输入音频,输出剩余的译音和转写文本,然后发送 session.closed 事件。只有翻译会话支持 session.close 事件。

发送 session.close 后,请停止追加音频,并在常规接收循环中继续读取事件,直到收到 session.closed。如果立即关闭套接字,可能会丢失会话尚未发送完的翻译结果。

关闭翻译会话
let translationSessionClosing = false;
let gotTranslationClosed = false;
let drainDeadline: ReturnType<typeof setTimeout> | undefined;

ws.on("close", () => {
  clearTimeout(drainDeadline);
  if (!gotTranslationClosed) {
    console.error("Translation disconnected before final session.closed");
    process.exitCode = 1;
  }
});

function closeTranslationSession() {
  if (translationSessionClosing) {
    return;
  }

  translationSessionClosing = true;
  // Adjust this deadline for your application's finalization requirements.
  drainDeadline = setTimeout(() => {
    console.error("Translation finalization timed out");
    process.exitCode = 1;
    ws.close();
  }, 15_000);
  ws.send(JSON.stringify({ type: "session.close" }));
}

// Use this in place of the earlier output handler, so audio plays only once.
ws.on("message", (data) => {
  const event = JSON.parse(data.toString());

  if (event.type === "session.output_audio.delta") {
    playPcm16(event.delta);
  }

  if (event.type === "session.output_transcript.delta") {
    process.stdout.write(event.delta);
  }

  if (event.type === "session.input_transcript.delta") {
    updateSourceTranscript(event.delta);
  }

  if (event.type === "error") {
    clearTimeout(drainDeadline);
    console.error("Translation error", event.error?.code);
    process.exitCode = 1;
    ws.close();
  }

  if (event.type === "session.closed") {
    clearTimeout(drainDeadline);
    gotTranslationClosed = true;
    ws.close();
  }
});

// Call this when the source stream ends.
closeTranslationSession();

为听众提供实时翻译

如果需要为听众提供来自一位说话者或一路音频流的译音,可以采用这种方式。适用场景包括直播、会议演讲、网络研讨会、财报电话会议、讲座和视频。

典型架构如下图所示。

源音频 -> 翻译会话 -> 译音 + 字幕

为每种目标语言创建一个翻译会话。如果同一路英语音频需要同时翻译成西班牙语和法语,请分别创建英语到西班牙语、英语到法语的翻译会话。

如果应用在浏览器中为听众提供翻译,请使用 getDisplayMedia() 采集标签页音频,通过 WebRTC 发送音频,然后播放远端译音轨道。对于生产环境中的广播,请在服务器端媒体处理进程中运行翻译,并向听众发布译音轨道或字幕。

为对话提供实时翻译

当两名或更多参与者使用不同语言交流时,可以使用对话翻译。适用场景包括客服通话、销售通话、辅导课和视频聊天室。

请为每位参与者保留独立音轨。将多人语音混合到一路音频流中,会增加识别说话者、为每位说话者显示字幕以及处理多人同时讲话的难度。

对于双人通话,请按下图为每个翻译方向各创建一个翻译会话。

通话者 A 的音频 -> 翻译成通话者 B 使用的语言 -> 播放给通话者 B
通话者 B 的音频 -> 翻译成通话者 A 使用的语言 -> 播放给通话者 A

对于多人聊天室,可根据正在发言的说话者音轨数和不同目标语言的数量估算会话数。

翻译会话数 ~= 正在发言的说话者的源音轨数 x 不同目标语言的数量

在小型聊天室中,每位听众可以在浏览器端为需要翻译的远端说话者分别创建辅助翻译组件。在较大的聊天室中,请使用服务器端的参会客户端或媒体处理进程,订阅每位说话者的源音轨一次,为每种目标语言各创建一个翻译会话,再重新发布译音轨道。

测试翻译质量和延迟

请使用真实音频测试翻译,并请熟悉两种语言的人员审查结果。自动化指标可以辅助评估,但无法发现用户会注意到的所有错误。

测试时请检查以下项目。

  • 各语言对的翻译质量
  • 姓名、数字、日期、货币和电话号码的翻译
  • 专业术语的翻译
  • 对话中切换或混用语言的情况
  • 带口音、语速快或多人同时说话的情况
  • 首段译音的输出延迟
  • 一段话说完后的延迟
  • 字幕显示时机
  • 声音的一致性
  • 重新连接时的行为

如果您的应用场景要求准确翻译名称或专业术语,请在上线前建立一套带有标准答案的测试样例,并人工审查未通过的样例。

上线检查清单

  • 浏览器端媒体传输使用 WebRTC,服务器端媒体传输使用 WebSocket。
  • 使用专用的 /v1/realtime/translations 端点。
  • 持续传输音频,包括讲话间的静音片段。
  • 发送 session.close 并等待收到 session.closed 后,再关闭 WebSocket 会话。
  • 对话翻译中,为每位说话者保留独立音轨。
  • 为每种输出语言创建一个会话。
  • 根据需要同时显示源语言和目标语言的转写文本。
  • 提供原声、译音、字幕、静音和音量控件。
  • 显示正在重新连接、出现延迟和服务不可用等状态。
  • 分别跟踪延迟和翻译质量。

相关指南

Realtime API 与音频概览

比较语音智能体会话、翻译会话和转写会话。

WebRTC 连接

将浏览器媒体流接入实时会话。

WebSocket 连接

通过服务器端媒体管道流式传输原始音频。

实时转写

根据实时音频流式输出增量转写文本。