语音实时 API 参考

语音实时 API 为使用 WebSocket 连接启用语音的应用程序提供实时双向通信。 此 API 支持高级功能，包括语音识别、文本到语音合成、头像流式处理、动画数据和全面的音频处理功能。

API 使用通过 WebSocket 连接发送的 JSON 格式事件来管理对话、音频流、虚拟形象交互和实时响应。 事件分为客户端事件（从客户端发送到服务器）和服务器事件（从服务器发送到客户端）。

主要功能

• 实时音频处理：支持多种音频格式，包括采用各种采样率的 PCM16 和 G.711 编解码器
• 高级语音选项：OpenAI 语音、Azure 自定义语音、Azure 标准语音和 Azure 个人语音
• 虚拟形象集成：基于 WebRTC 的头像流式处理视频、动画和 blendshapes
• 智能轮次检测：多个 VAD 选项，包括 Azure 语义 VAD 和服务器端检测
• 音频增强：内置降噪和回声取消
• 函数调用：用于增强聊天功能的工具集成
• 灵活的会话管理：可配置的形式、指令和响应参数

客户端事件

语音实时 API 支持以下可从客户端发送到服务器的客户端事件：

session.update

更新会话的配置。 可以随时发送此事件，以修改语音、形式、轮次检测、工具和其他会话参数等设置。 请注意，使用特定模型初始化会话后，无法将其更改为另一个模型。

事件结构

{
  "type": "session.update",
  "session": {
    "modalities": ["text", "audio"],
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "instructions": "You are a helpful assistant. Be concise and friendly.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

属性

Azure 自定义语音的示例

{
  "type": "session.update",
  "session": {
    "voice": {
      "type": "azure-custom",
      "name": "my-custom-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "temperature": 0.7,
      "style": "cheerful"
    },
    "input_audio_noise_reduction": {
      "type": "azure_deep_noise_suppression"
    },
    "avatar": {
      "character": "lisa",
      "customized": false,
      "video": {
        "resolution": {
          "width": 1920,
          "height": 1080
        },
        "bitrate": 2000000
      }
    }
  }
}

session.avatar.connect

通过提供客户端的 SDP（会话说明协议）产品/服务进行 WebRTC 媒体协商来建立虚拟形象连接。 使用虚拟形象功能时，需要此事件。

事件结构

{
  "type": "session.avatar.connect",
  "client_sdp": "<client_sdp>"
}

属性

input_audio_buffer.append

将音频字节追加到输入音频缓冲区。

事件结构

{
  "type": "input_audio_buffer.append",
  "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

属性

input_audio_buffer.commit

提交用于处理的输入音频缓冲区。

事件结构

{
  "type": "input_audio_buffer.commit"
}

属性

input_audio_buffer.clear

清除输入音频缓冲区。

事件结构

{
  "type": "input_audio_buffer.clear"
}

属性

conversation.item.create

向聊天上下文添加新项。 这可以包括消息、函数调用和函数调用响应。 可以在对话历史记录中的特定位置插入项目。

事件结构

{
  "type": "conversation.item.create",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

属性

音频内容示例

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello there"
      }
    ]
  }
}

函数调用示例

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call",
    "name": "get_weather",
    "call_id": "call_123",
    "arguments": "{\"location\": \"San Francisco\", \"unit\": \"celsius\"}"
  }
}

conversation.item.retrieve

从对话历史记录中检索特定项。 这对于在消除噪音和 VAD 后检查已处理的音频非常有用。

事件结构

{
  "type": "conversation.item.retrieve",
  "item_id": "item_ABC123"
}

属性

conversation.item.truncate

截断助理消息的音频内容。 这对于在特定时间点停止播放以及将服务器的了解与客户端状态同步非常有用。

事件结构

{
  "type": "conversation.item.truncate",
  "item_id": "item_ABC123",
  "content_index": 0,
  "audio_end_ms": 5000
}

属性

conversation.item.delete

从对话历史记录中删除项目。

事件结构

{
  "type": "conversation.item.delete",
  "item_id": "item_ABC123"
}

属性

response.create

指示服务器通过模型推理创建响应。 此事件可以指定替代会话默认值的特定于响应的配置。

事件结构

{
  "type": "response.create",
  "response": {
    "modalities": ["text", "audio"],
    "instructions": "Be extra helpful and detailed.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "output_audio_format": "pcm16",
    "temperature": 0.7,
    "max_response_output_tokens": 1000
  }
}

属性

工具选项示例

{
  "type": "response.create",
  "response": {
    "modalities": ["text"],
    "tools": [
      {
        "type": "function",
        "name": "get_current_time",
        "description": "Get the current time",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      }
    ],
    "tool_choice": "get_current_time",
    "temperature": 0.3
  }
}

动画示例

{
  "type": "response.create",
  "response": {
    "modalities": ["audio", "animation"],
    "animation": {
      "model_name": "default",
      "outputs": ["blendshapes", "viseme_id"]
    },
    "voice": {
      "type": "azure-custom",
      "name": "my-expressive-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "style": "excited"
    }
  }
}

response.cancel

取消正在进行的响应。 这会立即停止响应生成和相关音频输出。

事件结构

{
  "type": "response.cancel"
}

属性

属性

RealtimeClientEventConversationItemTruncate

客户端 conversation.item.truncate 事件用于截断上一条助理消息的音频。 服务器生成的音频速度比实时快，因此当用户中断以截断发送到客户端但尚未播放的音频时，此事件非常有用。 服务器对音频的理解与客户端的播放是同步的。

截断音频会删除服务器端文本脚本，以确保上下文中不存在用户不知道的文本。

如果客户端事件成功，服务器将响应事件 conversation.item.truncated 。

事件结构

{
  "type": "conversation.item.truncate",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

属性

RealtimeClientEventInputAudioBufferAppend

客户端 input_audio_buffer.append 事件用于将音频字节追加到输入音频缓冲区。 音频缓冲区是可以写入到稍后提交的临时存储。

在服务器 VAD（语音活动检测）模式下，音频缓冲区用于检测语音，服务器决定何时提交。 禁用服务器 VAD 后，客户端可以选择每个事件中最多放置 15 MiB 的音频量。 例如，从客户端流式传输较小的区块可以让 VAD 响应更迅速。

与其他大多数客户端事件不同，服务器不会向客户端 input_audio_buffer.append 事件发送确认响应。

事件结构

{
  "type": "input_audio_buffer.append",
  "audio": "<audio>"
}

属性

RealtimeClientEventInputAudioBufferClear

客户端 input_audio_buffer.clear 事件用于清除缓冲区中的音频字节。

服务器使用事件 input_audio_buffer.cleared 进行响应。

事件结构

{
  "type": "input_audio_buffer.clear"
}

属性

RealtimeClientEventInputAudioBufferCommit

客户端 input_audio_buffer.commit 事件用于提交用户输入音频缓冲区，该缓冲区在会话中创建新的用户消息项。 如果 input_audio_transcription 为会话配置了音频，则会转录音频。

在服务器 VAD 模式下，客户端不需要发送此事件，服务器会自动提交音频缓冲区。 如果没有服务器 VAD，客户端必须提交音频缓冲区才能创建用户消息项。 如果输入音频缓冲区为空，则此客户端事件将生成错误。

提交输入音频缓冲区不会从模型创建响应。

服务器使用事件 input_audio_buffer.committed 进行响应。

事件结构

{
  "type": "input_audio_buffer.commit"
}

属性

RealtimeClientEventResponseCancel

客户端 response.cancel 事件用于取消正在进行的响应。

服务器将使用状态为 <a0/a0> 的事件进行响应。

事件结构

{
  "type": "response.cancel"
}

属性

RealtimeClientEventResponseCreate

客户端 response.create 事件用于指示服务器通过模型推理创建响应。 在服务器 VAD 模式下配置会话时，服务器会自动创建响应。

响应至少包括一个 item，并且可以有两个，在这种情况下，第二个是函数调用。 这些项目将追加到对话历史记录中。

服务器使用事件 response.created 、一个或多个项和内容事件（如 conversation.item.created 和 response.content_part.added）进行响应，最后一个 response.done 事件指示响应已完成。

事件结构

{
  "type": "response.create"
}

属性

RealtimeClientEventSessionUpdate

客户端 session.update 事件用于更新会话的默认配置。 客户端可以随时发送此事件来更新会话配置，并且任何字段都可以随时更新，语音除外。

仅更新存在的字段。 若要清除字段（例如 instructions），请传递一个空字符串。

服务器使用 session.updated 包含完整有效配置的事件进行响应。

事件结构

{
  "type": "session.update"
}

属性

服务器事件

语音实时 API 将以下服务器事件发送到客户端，以传达状态、响应和数据：

session.created

成功建立新会话时发送。 这是连接到 API 后收到的第一个事件。

事件结构

{
  "type": "session.created",
  "session": {
    "id": "sess_ABC123DEF456",
    "object": "realtime.session",
    "model": "gpt-realtime",
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful assistant.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

属性

session.updated

成功更新会话配置以响应 session.update 客户端事件时发送。

事件结构

{
  "type": "session.updated",
  "session": {
    "id": "sess_ABC123DEF456",
    "voice": {
      "type": "azure-custom",
      "name": "my-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012"
    },
    "temperature": 0.7,
    "avatar": {
      "character": "lisa",
      "customized": false
    }
  }
}

属性

session.avatar.connecting

指示正在建立虚拟形象 WebRTC 连接。 此事件在响应 session.avatar.connect 客户端事件时发送。

事件结构

{
  "type": "session.avatar.connecting",
  "server_sdp": "<server_sdp>"
}

属性

conversation.item.created

在通过客户端 conversation.item.create 事件或响应生成过程中自动将新项添加到会话时发送。

事件结构

{
  "type": "conversation.item.created",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

属性

音频项的示例

{
  "type": "conversation.item.created",
  "item": {
    "id": "item_GHI789",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": null,
        "transcript": "What's the weather like today?"
      }
    ]
  }
}

conversation.item.retrieved

发送响应 conversation.item.retrieve 客户端事件，提供请求的对话项。

属性

conversation.item.truncated

当客户端截断具有事件的早期助理音频消息项conversation.item.truncated时，将返回服务器conversation.item.truncate事件。 此事件用于将服务器对音频的理解与客户端的播放同步。

此事件截断音频并删除服务器端文本脚本，以确保用户不知道的上下文中没有文本。

事件结构

{
  "type": "conversation.item.truncated",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

属性

conversation.item.deleted

在响应 conversation.item.delete 客户端事件时发送，确认已从会话中删除指定项。

事件结构

{
  "type": "conversation.item.deleted",
  "item_id": "item_ABC123"
}

属性

response.created

在新的响应生成开始时发送。 这是响应序列中的第一个事件。

事件结构

{
  "type": "response.created",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "in_progress",
    "status_details": null,
    "output": [],
    "usage": {
      "total_tokens": 0,
      "input_tokens": 0,
      "output_tokens": 0
    }
  }
}

属性

response.done

完成响应生成时发送。 此事件包含包含所有输出项和使用情况统计信息的最终响应。

事件结构

{
  "type": "response.done",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "completed",
    "status_details": null,
    "output": [
      {
        "id": "item_DEF456",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
          }
        ]
      }
    ],
    "usage": {
      "total_tokens": 87,
      "input_tokens": 52,
      "output_tokens": 35,
      "input_token_details": {
        "cached_tokens": 0,
        "text_tokens": 45,
        "audio_tokens": 7
      },
      "output_token_details": {
        "text_tokens": 15,
        "audio_tokens": 20
      }
    }
  }
}

属性

response.output_item.added

在生成过程中将新的输出项添加到响应时发送。

事件结构

{
  "type": "response.output_item.added",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "in_progress",
    "role": "assistant",
    "content": []
  }
}

属性

response.output_item.done

输出项完成时发送。

事件结构

{
  "type": "response.output_item.done",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm doing well, thank you for asking."
      }
    ]
  }
}

属性

response.content_part.added

当在响应生成过程中将新内容部件添加到助理消息项时，将返回服务器 response.content_part.added 事件。

事件结构

{
  "type": "response.content_part.added",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": ""
  }
}

属性

response.content_part.done

当内容部件在助理消息项中完成流式处理时，将返回服务器 response.content_part.done 事件。

当响应中断、不完整或取消时，也会返回此事件。

事件结构

{
  "type": "response.content_part.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": "Hello! I'm doing well, thank you for asking."
  }
}

属性

response.text.delta

从模型流式处理文本内容。 在模型生成文本时以增量方式发送。

事件结构

{
  "type": "response.text.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm"
}

属性

response.text.done

在文本内容生成完成时发送。

事件结构

{
  "type": "response.text.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

属性

response.audio.delta

从模型流式传输音频内容。 音频以 base64 编码的数据的形式提供。

事件结构

{
  "type": "response.audio.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

属性

response.audio.done

当音频内容生成完成时发送。

事件结构

{
  "type": "response.audio.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

属性

response.audio_transcript.delta

生成的音频内容的流式处理脚本。

事件结构

{
  "type": "response.audio_transcript.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm doing"
}

属性

response.audio_transcript.done

当音频脚本生成完成时发送。

事件结构

{
  "type": "response.audio_transcript.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

属性

conversation.item.input_audio_transcription.completed

服务器 conversation.item.input_audio_transcription.completed 事件是写入音频缓冲区的语音听录的结果。

当客户端或服务器（模式） server_vad 提交输入音频缓冲区时，将开始听录。 脚本在创建响应时异步运行，因此此事件可以在响应事件之前或之后运行。

实时 API 模型以本机方式接受音频，因此输入听录是在单独的语音识别模型上运行的单独进程，例如 whisper-1。 因此，脚本可能会从模型的解释中略有不同，应被视为粗略的指南。

事件结构

{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "<item_id>",
  "content_index": 0,
  "transcript": "<transcript>"
}

属性

conversation.item.input_audio_transcription.delta

配置输入音频听录时，将返回服务器 conversation.item.input_audio_transcription.delta 事件，并且正在进行用户消息的听录请求。 此事件提供部分听录结果，因为它们可用。

事件结构

{
  "type": "conversation.item.input_audio_transcription.delta",
  "item_id": "<item_id>",
  "content_index": 0,
  "delta": "<delta>"
}

属性

conversation.item.input_audio_transcription.failed

配置输入音频听录时，将返回服务器 conversation.item.input_audio_transcription.failed 事件，并且用户消息的听录请求失败。 此事件与其他 error 事件分开，以便客户端能够标识相关项。

事件结构

{
  "type": "conversation.item.input_audio_transcription.failed",
  "item_id": "<item_id>",
  "content_index": 0,
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

属性

错误属性

response.animation_blendshapes.delta

当模型生成动画混合图形数据作为响应的一部分时，将返回服务器 response.animation_blendshapes.delta 事件。 此事件提供增量混合图形数据，因为它可用。

事件结构

{
  "type": "response.animation_blendshapes.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "frame_index": 0,
  "frames": [
    [0.0, 0.1, 0.2, ..., 1.0]
    ...
  ]
}

属性

response.animation_blendshapes.done

当模型完成生成动画混合图形数据作为响应的一部分时，将返回服务器 response.animation_blendshapes.done 事件。

事件结构

{
  "type": "response.animation_blendshapes.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
}

属性

response.audio_timestamp.delta

当模型生成音频时间戳数据作为响应的一部分时，将返回服务器 response.audio_timestamp.delta 事件。 此事件提供输出音频和文本对齐的增量时间戳数据，因为它变得可用。

事件结构

{
  "type": "response.audio_timestamp.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "audio_duration_ms": 500,
  "text": "Hello",
  "timestamp_type": "word"
}

属性

response.audio_timestamp.done

当音频时间戳生成完成时发送。

事件结构

{
  "type": "response.audio_timestamp.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

属性

response.animation_viseme.delta

当模型在响应过程中生成动画 viseme 数据时，将返回服务器 response.animation_viseme.delta 事件。 此事件在可用时提供增量 viseme 数据。

事件结构

{
  "type": "response.animation_viseme.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "viseme_id": 1
}

属性

response.animation_viseme.done

当模型完成作为响应的一部分生成动画视觉数据时，将返回服务器 response.animation_viseme.done 事件。

事件结构

{
  "type": "response.animation_viseme.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

属性

当模型在响应过程中生成动画 viseme 数据时，将返回服务器 response.animation_viseme.delta 事件。 此事件在可用时提供增量 viseme 数据。

错误

发生错误时会返回服务器 error 事件，这可能是客户端问题或服务器问题。 大多数错误都是可恢复的，会话保持打开状态。

事件结构

{
  "type": "error",
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>",
    "event_id": "<event_id>"
  }
}

属性

错误属性

input_audio_buffer.cleared

当客户端使用input_audio_buffer.cleared事件清除输入音频缓冲区时，将返回服务器input_audio_buffer.clear事件。

事件结构

{
  "type": "input_audio_buffer.cleared"
}

属性

input_audio_buffer.committed

当客户端提交输入音频缓冲区或在服务器 VAD 模式下自动提交时，将返回服务器 input_audio_buffer.committed 事件。 该 item_id 属性是创建的用户消息项的 ID。 因此， conversation.item.created 事件也会发送到客户端。

事件结构

{
  "type": "input_audio_buffer.committed",
  "previous_item_id": "<previous_item_id>",
  "item_id": "<item_id>"
}

属性

input_audio_buffer.speech_started

input_audio_buffer.speech_started在音频缓冲区中检测到语音时，服务器事件以模式返回server_vad。 只要音频添加到缓冲区（除非检测到语音），此事件可能会发生。

客户端应在语音停止时收到 input_audio_buffer.speech_stopped 事件。 该 item_id 属性是语音停止时创建的用户消息项的 ID。 item_id除非客户端在 VAD 激活期间手动提交音频缓冲区，否则该事件也包含在input_audio_buffer.speech_stopped事件中。

事件结构

{
  "type": "input_audio_buffer.speech_started",
  "audio_start_ms": 0,
  "item_id": "<item_id>"
}

属性

input_audio_buffer.speech_stopped

服务器在音频缓冲区中检测到语音结束时，以模式返回input_audio_buffer.speech_stopped服务器server_vad事件。

服务器还会发送一个 conversation.item.created 事件，其中包含从音频缓冲区创建的用户消息项。

事件结构

{
  "type": "input_audio_buffer.speech_stopped",
  "audio_end_ms": 0,
  "item_id": "<item_id>"
}

属性

rate_limits.updated

rate_limits.updated服务器事件在响应开始时发出，以指示更新的速率限制。

创建响应时，某些令牌将保留给输出令牌。 此处显示的速率限制反映预留，然后在响应完成后相应地进行调整。

事件结构

{
  "type": "rate_limits.updated",
  "rate_limits": [
    {
      "name": "<name>",
      "limit": 0,
      "remaining": 0,
      "reset_seconds": 0
    }
  ]
}

属性

response.audio.delta

更新模型生成的音频时，将返回服务器 response.audio.delta 事件。

事件结构

{
  "type": "response.audio.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

属性

response.audio.done

模型生成的音频完成后，将返回服务器 response.audio.done 事件。

当响应中断、不完整或取消时，也会返回此事件。

事件结构

{
  "type": "response.audio.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0
}

属性

response.audio_transcript.delta

更新音频输出的模型生成的听录时，将返回服务器 response.audio_transcript.delta 事件。

事件结构

{
  "type": "response.audio_transcript.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

属性

response.audio_transcript.done

当音频输出的模型生成的听录完成流式处理时，将返回服务器 response.audio_transcript.done 事件。

当响应中断、不完整或取消时，也会返回此事件。

事件结构

{
  "type": "response.audio_transcript.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "transcript": "<transcript>"
}

属性

response.function_call_arguments.delta

更新模型生成的函数调用参数时，将返回服务器 response.function_call_arguments.delta 事件。

事件结构

{
  "type": "response.function_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "delta": "<delta>"
}

属性

response.function_call_arguments.done

当模型生成的函数调用参数完成流式处理时，将返回服务器 response.function_call_arguments.done 事件。

当响应中断、不完整或取消时，也会返回此事件。

事件结构

{
  "type": "response.function_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "arguments": "<arguments>"
}

属性

response.output_item.added

在响应生成期间创建新项时，将返回服务器 response.output_item.added 事件。

事件结构

{
  "type": "response.output_item.added",
  "response_id": "<response_id>",
  "output_index": 0
}

属性

response.output_item.done

当项完成流式处理时，将返回服务器 response.output_item.done 事件。

当响应中断、不完整或取消时，也会返回此事件。

事件结构

{
  "type": "response.output_item.done",
  "response_id": "<response_id>",
  "output_index": 0
}

属性

response.text.delta

更新模型生成的文本时，将返回服务器 response.text.delta 事件。 文本对应于 text 助理消息项的内容部分。

事件结构

{
  "type": "response.text.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

属性

response.text.done

当模型生成的文本完成流式处理时，将返回服务器 response.text.done 事件。 文本对应于 text 助理消息项的内容部分。

当响应中断、不完整或取消时，也会返回此事件。

事件结构

{
  "type": "response.text.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "text": "<text>"
}

属性

Components

音频格式

RealtimeAudioFormat

用于输入音频的基本音频格式。

允许的值：

• pcm16 - 16 位 PCM 音频格式
• g711_ulaw - G.711 μ法律音频格式
• g711_alaw - G.711 A-law 音频格式

RealtimeOutputAudioFormat

用于具有特定采样率的输出音频的音频格式。

允许的值：

• pcm16 - 默认采样率为 16 位 PCM 音频格式（24kHz）
• pcm16_8000hz - 16 位 PCM 音频格式，采用 8kHz 采样率
• pcm16_16000hz - 16 位 PCM 音频格式，采样率为 16kHz
• g711_ulaw - G.711 μ-law （mu-law） 音频格式，采用 8kHz 采样率
• g711_alaw - G.711 A-law 音频格式（采用 8kHz 采样率）

RealtimeAudioInputTranscriptionSettings

输入音频转录的配置。

RealtimeInputAudioNoiseReductionSettings

输入音频降噪的配置。

RealtimeInputAudioEchoCancellationSettings

服务器端音频处理的回声取消配置。

语音配置

RealtimeVoice

所有支持的语音配置的联合。

这可以是：

• RealtimeOpenAIVoice 对象
• RealtimeAzureVoice 对象

RealtimeOpenAIVoice

具有显式类型字段的 OpenAI 语音配置。

RealtimeAzureVoice

Azure 语音配置的基数。 这是不同类型的区分联合：

RealtimeAzureCustomVoice

Azure 自定义语音配置（首选用于自定义语音）。

示例：

{
  "type": "azure-custom",
  "name": "my-custom-voice",
  "endpoint_id": "12345678-1234-1234-1234-123456789012",
  "temperature": 0.7,
  "style": "cheerful",
  "locale": "en-US"
}

RealtimeAzureStandardVoice

Azure 标准语音配置。

RealtimeAzurePersonalVoice

Azure 个人语音配置。

轮次检测

RealtimeTurnDetection

轮次检测的配置。 这是支持多个 VAD 类型的歧视联合。

RealtimeServerVad

基于 VAD 的基本轮次检测。

RealtimeAzureSemanticVad

Azure 语义 VAD（默认变体）。

RealtimeEOUDetection

Azure 言语结束（EOU）可以指示最终用户何时停止说话，同时允许自然暂停。 话语结束检测可以显著减少过早的谈话结束信号，而无需增加用户可察觉的延迟。

虚拟形象配置

RealtimeAvatarConfig

虚拟形象流式处理和行为的配置。

RealtimeIceServer

WebRTC 连接协商的 ICE 服务器配置。

RealtimeVideoParams

虚拟形象的视频流式处理参数。

RealtimeVideoCrop

视频裁剪矩形定义。

RealtimeVideoResolution

视频分辨率规范。

动画配置

RealtimeAnimation

动画输出的配置，包括 blendshapes 和 visemes。

RealtimeAnimationOutputType

要输出的动画数据类型。

允许的值：

• blendshapes - 面部混合图形数据
• viseme_id - Viseme 标识符数据

会话配置

RealtimeRequestSession

事件中使用的 session.update 会话配置对象。

RealtimeModality

支持的会话形式。

允许的值：

• text - 文本输入/输出
• audio - 音频输入/输出
• animation - 动画输出
• avatar - 虚拟形象视频输出

RealtimeAudioTimestampType

音频响应内容支持的输出时间戳类型。

允许的值：

• word - 输出音频中每字的时间戳

工具配置

RealtimeTool

函数调用的工具定义。

RealtimeToolChoice

工具选择策略。

这可以是：

• "auto" - 让模型选择
• "none" - 不使用工具
• "required" - 必须使用工具
• { "type": "function", "name": "function_name" } - 使用特定函数

RealtimeConversationResponseItem

这是一种联合类型，可以是下列类型之一：

RealtimeConversationUserMessageItem

用户消息项。

RealtimeConversationAssistantMessageItem

助理消息项。

RealtimeConversationSystemMessageItem

系统消息项。

RealtimeConversationFunctionCallItem

函数调用请求项。

RealtimeConversationFunctionCallOutputItem

函数调用响应项。

RealtimeItemStatus

对话项的状态。

允许的值：

• in_progress - 当前正在处理
• completed - 成功完成
• incomplete - 不完整（中断或失败）

RealtimeContentPart

消息中的内容部件。

RealtimeInputTextContentPart

文本内容部件。

RealtimeOutputTextContentPart

文本内容部件。

RealtimeInputAudioContentPart

音频内容部分。

RealtimeOutputAudioContentPart

音频内容部分。

响应对象

RealtimeResponse

表示模型推理响应的响应对象。

RealtimeResponseStatus

响应状态值。

允许的值：

• in_progress - 正在生成响应
• completed - 响应成功完成
• cancelled - 响应已取消
• incomplete - 响应不完整（中断）
• failed - 响应失败并出现错误

RealtimeUsage

令牌使用情况统计信息。

TokenDetails

详细的令牌使用情况细分。

错误处理

RealtimeErrorDetails

错误信息对象。

RealtimeConversationRequestItem

使用 RealtimeConversationRequestItem 对象通过 conversation.item.create 事件在会话中创建新项。

这是一种联合类型，可以是下列类型之一：

RealtimeSystemMessageItem

系统消息项。

RealtimeUserMessageItem

用户消息项。

RealtimeAssistantMessageItem

助理消息项。

RealtimeFunctionCallItem

函数调用项。

RealtimeFunctionCallOutputItem

函数调用输出项。

RealtimeFunctionTool

实时终结点使用的函数工具的定义。

RealtimeItemStatus

允许的值：

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

该 RealtimeResponseSession 对象表示实时 API 中的会话。 它用于某些服务器事件，例如：

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

相关资源

• 试用 语音在线快速入门
• 试用语音实时代理快速入门
• 详细了解 如何使用语音实时 API