OpenAI Realtime 翻译服务端事件

Realtime 翻译服务端事件

以下事件由 OpenAI Realtime Translation WebSocket 服务器发送给客户端。

error

发生错误时返回，错误可能来自客户端或服务端问题。大多数错误可恢复，会话会保持打开。建议默认监控并记录错误消息。

结构定义

结构名称为 RealtimeServerEventError。

error: RealtimeError

错误详情。

message: string

便于人类阅读的错误消息。

type: string

错误类型，例如 "invalid_request_error" 或 "server_error"。

code: optional string or null

错误代码（如有）。

event_id: optional string or null

导致错误的客户端事件 event_id（如适用）。

param: optional string or null

与错误有关的参数（如有）。

event_id: string

服务端事件的唯一 ID。

type: "error"

事件类型，必须为 error.

"error"

示例

{
    "event_id": "event_890",
    "type": "error",
    "error": {
        "type": "invalid_request_error",
        "code": "invalid_event",
        "message": "The 'type' field is missing.",
        "param": null,
        "event_id": "event_567"
    }
}

session.created

创建翻译会话时返回。在建立新连接后自动发出，作为第一个服务端事件。事件包含默认翻译会话配置。

结构定义

结构名称为 RealtimeTranslationServerEventSessionCreated。

event_id: string

服务端事件的唯一 ID。

session: RealtimeTranslationSession

翻译会话配置。

id: string

会话唯一标识，类似 sess_1234567890abcdef。

audio: object { input, output }

翻译输入与输出音频的配置。

input: optional object { noise_reduction, transcription }

noise_reduction: optional object { type, strength } or null

可选的输入降噪配置。

type: NoiseReductionType

降噪类型。near_field 适用于耳机等近讲麦克风，far_field 适用于笔记本或会议室等远场麦克风。

"near_field"

"far_field"

strength: optional number (default: 1)

输入噪声抑制强度，值越大抑制越强。首次启用降噪时默认为 1。在会话更新中省略 strength 会保留当前强度。

minimum: 0, maximum: 1

transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta events. Translation itself still runs from 输入音频流。

model: string

用于生成源语言转录文本增量的转录模型。

output: optional object { language }

language: optional string

翻译后音频与文本增量的目标语言。

expires_at: integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

model: string

此会话使用的 Realtime 翻译模型。此字段在创建会话时设置，无法通过 session.update 修改。

type: "translation"

会话类型，Realtime 翻译会话固定为 translation。

"translation"

type: "session.created"

事件类型，必须为 session.created.

"session.created"

示例

{
  "type": "session.created",
  "event_id": "event_123",
  "session": {
    "id": "sess_123",
    "type": "translation",
    "model": "gpt-realtime-translate",
    "expires_at": 1714857600,
    "audio": {
      "input": {
        "transcription": {
          "model": "gpt-realtime-whisper",
          "language": "en"
        },
        "noise_reduction": {
          "type": "near_field"
        }
      },
      "output": {
        "language": "fr"
      }
    }
  }
}

session.updated

通过 session.update 事件更新翻译会话后返回，发生错误时除外。

结构定义

结构名称为 RealtimeTranslationServerEventSessionUpdated。

event_id: string

服务端事件的唯一 ID。

session: RealtimeTranslationSession

翻译会话配置。

id: string

会话唯一标识，类似 sess_1234567890abcdef。

audio: object { input, output }

翻译输入与输出音频的配置。

input: optional object { noise_reduction, transcription }

noise_reduction: optional object { type, strength } or null

可选的输入降噪配置。

type: NoiseReductionType

降噪类型。near_field 适用于耳机等近讲麦克风，far_field 适用于笔记本或会议室等远场麦克风。

"near_field"

"far_field"

strength: optional number (default: 1)

输入噪声抑制强度，值越大抑制越强。首次启用降噪时默认为 1。在会话更新中省略 strength 会保留当前强度。

minimum: 0, maximum: 1

transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta events. Translation itself still runs from 输入音频流。

model: string

用于生成源语言转录文本增量的转录模型。

output: optional object { language }

language: optional string

翻译后音频与文本增量的目标语言。

expires_at: integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

model: string

此会话使用的 Realtime 翻译模型。此字段在创建会话时设置，无法通过 session.update 修改。

type: "translation"

会话类型，Realtime 翻译会话固定为 translation。

"translation"

type: "session.updated"

事件类型，必须为 session.updated.

"session.updated"

示例

{
  "type": "session.updated",
  "event_id": "event_124",
  "session": {
    "id": "sess_123",
    "type": "translation",
    "model": "gpt-realtime-translate",
    "expires_at": 1714857600,
    "audio": {
      "input": {
        "transcription": {
          "model": "gpt-realtime-whisper",
          "language": "en"
        },
        "noise_reduction": {
          "type": "near_field"
        }
      },
      "output": {
        "language": "es"
      }
    }
  }
}

session.closed

实时翻译会话关闭时返回。

结构定义

结构名称为 RealtimeTranslationServerEventSessionClosed。

event_id: string

服务端事件的唯一 ID。

type: "session.closed"

事件类型，必须为 session.closed.

"session.closed"

示例

{
  "event_id": "event_987",
  "type": "session.closed"
}

session.input_transcript.delta

可选的源语言转录文本可用时返回。此事件仅在配置 audio.input.transcription 后发出。

转录文本增量是只能追加的文本片段。客户端不应在增量之间无条件插入空格。

结构定义

结构名称为 RealtimeTranslationServerEventSessionInputTranscriptDelta。

delta: string

只能追加的源语言转录文本。

event_id: string

服务端事件的唯一 ID。

type: "session.input_transcript.delta"

事件类型，必须为 session.input_transcript.delta.

"session.input_transcript.delta"

elapsed_ms: optional integer or null

用于流对齐的时间元数据，来源于翻译帧（如可用）。时间以 200 毫秒递增，但多个文本增量可能具有相同的 elapsed_ms。应将其视为对齐元数据，不能将其视为文本增量的唯一标识。

示例

{
  "event_id": "event_125",
  "type": "session.input_transcript.delta",
  "delta": " hear",
  "elapsed_ms": 1200
}

session.output_transcript.delta

翻译后的转录文本可用时返回。

转录文本增量是只能追加的文本片段。客户端不应在增量之间无条件插入空格。

结构定义

结构名称为 RealtimeTranslationServerEventSessionOutputTranscriptDelta。

delta: string

只能追加的、与翻译后输出音频对应的转录文本。

event_id: string

服务端事件的唯一 ID。

type: "session.output_transcript.delta"

事件类型，必须为 session.output_transcript.delta.

"session.output_transcript.delta"

elapsed_ms: optional integer or null

示例

{
  "event_id": "event_124",
  "type": "session.output_transcript.delta",
  "delta": " escuch",
  "elapsed_ms": 1200
}

session.output_audio.delta

翻译后的输出音频可用时返回。delta 包含长度可能变化的 PCM16 音频块。客户端应解码并将完整增量加入队列，不应假定固定字节数或采样数。

结构定义

结构名称为 RealtimeTranslationServerEventSessionOutputAudioDelta。

delta: string

Base64 编码的翻译后音频数据。

event_id: string

服务端事件的唯一 ID。

type: "session.output_audio.delta"

事件类型，必须为 session.output_audio.delta.

"session.output_audio.delta"

channels: optional integer (default: 1)

音频声道数。

elapsed_ms: optional integer or null

用于流对齐的时间元数据，来源于翻译帧（如可用）。elapsed_ms 是对齐元数据，不是唯一事件标识。

format: optional "pcm16"

音频增量 delta 的编码。

"pcm16"

sample_rate: optional integer (default: 24000)

音频增量的采样率。

示例

{
  "event_id": "event_123",
  "type": "session.output_audio.delta",
  "delta": "Base64EncodedAudioDelta",
  "sample_rate": 24000,
  "channels": 1,
  "format": "pcm16",
  "elapsed_ms": 1200
}