如何使用语音实时 API

与 Azure OpenAI 实时 API 相比，语音实时 API 提供了一个更强大的 WebSocket 接口。

除非另有说明，否则语音实时 API 使用与 Azure OpenAI 实时 API 相同的事件 。 本文档提供特定于语音实时 API 的事件消息属性的参考。

支持的模型和区域

有关支持的模型和区域的表，请参阅 语音实时 API 概述。

Authentication

访问语音实时 API 需要 Azure AI Foundry 资源 。

WebSocket 终结点

语音实时 API 的 WebSocket 终结点是 wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01，或对于较旧的资源是 wss://<your-ai-foundry-resource-name>.cognitiveservices.azure.com/voice-live/realtime?api-version=2025-10-01。 所有模型的终结点都是相同的。 唯一的区别在于所需的 model 查询参数，或者在使用代理服务时，需要包含 agent_id 和 project_id 参数。

例如，具有自定义域的资源的终结点将是 wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01&model=gpt-realtime

Credentials

语音实时 API 支持两种身份验证方法：

• Microsoft Entra （建议）：对 Azure AI Foundry 资源使用基于令牌的身份验证。 将 Bearer 令牌与 Authorization 标头配合使用来应用一个检索到的身份验证令牌。
• API 密钥：可通过以下两种方式之一提供 api-key：
  • 对预握手连接使用 api-key 连接标头。 此选项在浏览器环境中不可用。
  • 对请求 URI 使用 api-key 查询字符串参数。 使用 https/wss 时，查询字符串参数是加密的。

若要使用 Microsoft Entra ID 进行推荐的无密钥身份验证，你需要：

• 将 Cognitive Services User 角色分配给用户帐户或托管标识。 你可以在 Azure 门户的“访问控制(IAM)”“添加角色分配”下分配角色。>
• 使用 Azure CLI 或 Azure SDK 生成令牌。 令牌必须使用 https://ai.azure.com/.default 范围生成，或者也可以使用旧的 https://cognitiveservices.azure.com/.default 范围。
• 使用 WebSocket 连接请求标头中的 Authorization 令牌，格式为 Bearer <token>。

会话配置

通常，调用方在新建立的语音实时 API 会话上发送的第一个事件就是该 session.update 事件。 此事件控制一组广泛的输入和输出行为，输出和响应生成属性随后可以使用 response.create 事件来进行重写。

下面是一条示例 session.update 消息，用于配置会话的多个方面，包括轮次检测、输入音频处理和语音输出。 大多数会话参数都是可选的，如果需要，可以省略这些参数。

{
    "instructions": "You are a helpful AI assistant responding in natural, engaging language.",
    "turn_detection": {
        "type": "azure_semantic_vad",
        "threshold": 0.3,
        "prefix_padding_ms": 200,
        "silence_duration_ms": 200,
        "remove_filler_words": false,
        "end_of_utterance_detection": {
            "model": "semantic_detection_v1",
            "threshold": 0.01,
            "timeout": 2,
        },
    },
    "input_audio_noise_reduction": {"type": "azure_deep_noise_suppression"},
    "input_audio_echo_cancellation": {"type": "server_echo_cancellation"},
    "voice": {
        "name": "en-US-Ava:DragonHDLatestNeural",
        "type": "azure-standard",
        "temperature": 0.8,
    },
}

服务器通过 session.updated 事件做出响应，以确认会话配置。

会话属性

以下部分描述了可在session消息中配置的session.update对象的属性。

输入音频属性

可以使用输入音频属性来配置输入音频流。

这里有一个输入音频属性的示例：它是一个会话对象。

{
    "input_audio_sampling_rate": 24000,
    "input_audio_noise_reduction": {"type": "azure_deep_noise_suppression"},
    "input_audio_echo_cancellation": {"type": "server_echo_cancellation"},
}

干扰抑制和回声消除

噪音抑制通过抑制或删除环境背景噪音来提高输入音频质量。 干扰抑制有助于模型以更高的准确度了解最终用户，并提高信号的准确性，如中断检测和轮次检测。

服务器回声消除通过从模型自己的语音中删除回声来增强输入音频质量。 这样，不需要进行客户端回声消除。 当模型的声音通过扬声器传递到最终用户，而麦克风捕捉到模型自己的声音时，服务器回声消除非常有用。

对话增强

语音实时 API 提供聊天增强功能，为自然最终用户聊天流提供稳定性。

轮次检测参数

轮次检测是检测最终用户何时启动或停止说话的过程。 语音实时 API 基于 Azure OpenAI 实时 API turn_detection 属性构建，用于配置轮次检测。 azure_semantic_vad 类型和高级 end_of_utterance_detection 是区分语音实时 API 和 Azure OpenAI 实时 API 的关键因素。

下面是会话对象中话语结束检测的示例：

{
    "session": {
        "instructions": "You are a helpful AI assistant responding in natural, engaging language.",
        "turn_detection": {
            "type": "azure_semantic_vad",
            "threshold": 0.3,
            "prefix_padding_ms": 300,
            "speech_duration_ms":80,
            "silence_duration_ms": 500,
            "remove_filler_words": false,
            "end_of_utterance_detection": {
                "model": "semantic_detection_v1",
                "threshold": 0.01,
                "timeout": 2
            }
        }
    }
}

通过 Azure 语音转文本的音频输入

使用 gpt-4o 等非多模式模型时，Azure 语音转文本将自动处于活动状态。

为了显式配置它，可以在 model 中将 azure-speech 设置为 input_audio_transcription。 这对于提高特定语言情况的识别质量非常有用。 请参阅 如何自定义语音实时输入和输出 ，详细了解语音输入自定义配置。

{
    "session": {
        "input_audio_transcription": {
            "model": "azure-speech",
            "language": "en"
        }
    }
}

通过 Azure 文本转语音进行的音频输出

可以使用 voice 参数指定标准语音或自定义语音。 语音用于音频输出。

voice 对象具有以下属性：

请参阅 如何自定义语音实时输入和输出 ，详细了解语音输入自定义配置。

Azure 标准语音

下面是标准 (azure-standard) 语音的不完整消息示例：

{
  "voice": {
    "name": "en-US-AvaNeural",
    "type": "azure-standard"
  }
}

有关标准语音的完整列表，请参阅 语音服务的语言和语音支持。

Azure 高清语音

下面是标准高清音频的示例消息 session.update：

{
  "voice": {
    "name": "en-US-Ava:DragonHDLatestNeural",
    "type": "azure-standard",
    "temperature": 0.8 // optional
  }
}

有关标准高清语音的完整列表，请参阅 高清语音文档。

语速

使用 rate 字符串属性可以调整任何标准 Azure 文字转语音声音和自定义声音的说话速度。

速率值应从 0.5 到 1.5 不等，值越高，表示速度越快。

{
  "voice": {
    "name": "en-US-Ava:DragonHDLatestNeural",
    "type": "azure-standard",
    "temperature": 0.8, // optional
    "rate": "1.2"
  }
}

音频时间戳

当您使用 Azure 声音并配置 output_audio_timestamp_types 时，服务会在响应中返回 response.audio_timestamp.delta，并在返回所有时间戳消息时返回 response.audio_timestamp.done。

若要配置音频时间戳，可以在 session.update 消息中设置 output_audio_timestamp_types 。

{
    "session": {
        "output_audio_timestamp_types": ["word"]
    }
}

生成音频时，服务在响应中返回音频时间戳。

{
    "event_id": "<event_id>",
    "type": "response.audio_timestamp.delta",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
    "output_index": 0,
    "content_index": 0,
    "audio_offset_ms": 490,
    "audio_duration_ms": 387,
    "text": "end",
    "timestamp_type": "word"
}

当返回所有时间戳时，将发送一 response.audio_timestamp.done 条消息。

{
    "event_id": "<event_id>",
    "type": "response.audio_timestamp.done",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
}

Viseme

视素是口语中音素的视觉描述。 它定义了一个人说话时面部和嘴巴的位置。

您可以使用 Azure 标准语音或将animation.outputs设置为{"viseme_id"}的 Azure 自定义语音。 服务在响应中返回 response.animation_viseme.delta，及在所有 viseme 消息返回时返回 response.animation_viseme.done。

若要配置 viseme，可以在 animation.outputs 消息中设置 session.update。 animation.outputs 参数是可选的。 它配置应返回哪些动画输出。 目前，它仅支持 viseme_id。

{
  "type": "session.update",
  "event_id": "your-session-id",
  "session": {
    "voice": {
      "name": "en-US-AvaNeural",
      "type": "azure-standard",
    },
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful AI assistant responding in natural, engaging language.",
    "turn_detection": {
        "type": "server_vad"
    },
    "output_audio_timestamp_types": ["word"], // optional
    "animation": {
        "outputs": ["viseme_id"], // optional
    },
  }
}

output_audio_timestamp_types 参数是可选的。 它配置应为生成的音频返回哪些音频时间戳。 目前，它仅支持 word。

生成音频时，服务会在响应中返回视素对齐信息。

{
    "event_id": "<event_id>",
    "type": "response.animation_viseme.delta",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
    "output_index": 0,
    "content_index": 0,
    "audio_offset_ms": 455,
    "viseme_id": 20
}

返回所有视素消息时，会发送 response.animation_viseme.done 消息。

{
    "event_id": "<event_id>",
    "type": "response.animation_viseme.done",
    "response_id": "<response_id>",
    "item_id": "<item_id>",
}

Azure 文本转语音虚拟形象

文本转语音虚拟形象将文本转换为拟真人物（标准虚拟形象或自定义文本转语音虚拟形象）以自然声音说话的数字视频。

可以使用参数 avatar 指定标准或自定义头像。 虚拟形象与音频输出同步。

可以指定参数 avatar 以启用与音频输出同步的虚拟形象输出：

{
  "session": {
    "avatar": {
      "character": "lisa",
      "style": "casual-sitting",
      "customized": false,
      "ice_servers": [
        {
          "urls": ["REDACTED"],
          "username": "",
          "credential": ""
        }
      ],
      "video": {
        "bitrate": 2000000,
        "codec": "h264",
        "crop": {
          "top_left": [560, 0],
          "bottom_right": [1360, 1080],
        },
        "resolution": {
          "width": 1080,
          "height": 1920,
        },
        "background": {
          "color": "#00FF00FF"
          // "image_url": "https://example.com/example.jpg"
        }
      }
    }
  }
}

ice_servers 字段为可选。 如果未指定，服务将在 session.updated 响应中返回特定于服务器的 ICE 服务器。 你需要使用服务器专用的 ICE 服务器来生成本地 ICE 候选者。

收集 ICE 候选项后，发送客户端 SDP。

{
    "type": "session.avatar.connect",
    "client_sdp": "your-client-sdp"
}

服务使用服务器 SDP 进行响应。

{
    "type": "session.avatar.connecting",
    "server_sdp": "your-server-sdp"
}

然后，可以将头像与服务器 SDP 连接。

相关内容

• 试用 语音实时 API 快速入门
• 请参阅 语音实时 API 参考