Использование API голосовой трансляции

API Voice Live предоставляет более мощный интерфейс WebSocket по сравнению с API Azure OpenAI Realtime.

Если не указано иное, API голосовой трансляции использует те же события , что и API Azure OpenAI Realtime. Этот документ содержит ссылку на свойства сообщения о событии, относящиеся к API голосовой трансляции.

Поддерживаемые модели и регионы

Сведения о поддерживаемых моделях и регионах см. в обзоре API голосовой трансляции.

Authentication

Ресурс Microsoft Foundry или ресурс Azure Speech in Foundry Tools Services требуется для использования API Live Голоса.

Конечная точка WebSocket

Конечная точка WebSocket для API голосовой трансляции — это 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 (рекомендуется): используйте проверку подлинности на основе маркеров для ресурса Microsoft Foundry. Примените полученный маркер проверки подлинности, используя маркер с заголовком Bearer и Authorization.
• Ключ API: api-key можно предоставить одним из двух способов:
  • Использование заголовка api-key подключения в предварительном установлении соединения. Этот параметр недоступен в среде браузера.
  • api-key Использование параметра строки запроса в URI запроса. Параметры строки запроса шифруются при использовании https/wss.

Для рекомендуемой проверки подлинности без ключа с помощью идентификатора Microsoft Entra необходимо:

• Назначьте роли Cognitive Services User и Azure AI User вашей учетной записи пользователя или управляемому удостоверению. Роли можно назначить в портале Azure в разделе Контроль доступа (IAM)>Добавить назначение ролей.
• Создайте токен с помощью Azure CLI или пакетов SDK Azure. Маркер должен быть создан с областью https://ai.azure.com/.default, или с устаревшей областью https://cognitiveservices.azure.com/.default.
• Используйте маркер в Authorization заголовке запроса на подключение WebSocket с форматом Bearer <token>.

Конфигурация сеанса

Часто первое событие, отправленное вызывающим абонентом в только что созданном сеансе голосового API Live, является событием session.update . Это событие управляет широким набором поведения ввода и вывода с характеристиками генерации выходных данных и откликов. Затем эти характеристики могут быть переопределены с помощью события response.create.

Ниже приведен пример session.update сообщения, который настраивает несколько аспектов сеанса, включая обнаружение поворота, входную обработку звука и выход голосовой связи. Большинство параметров сеанса являются необязательными и могут быть опущены при необходимости.

{
    "instructions": "You are a helpful AI assistant responding in natural, engaging language.",
    "turn_detection": {
        "type": "azure_semantic_vad",
        "silence_duration_ms": 500,
    },
    "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 Voice Live основан на свойстве API turn_detection Azure OpenAI Realtime для настройки обнаружения поворота. Эти типы azure_semantic_vad и azure_multilingual_semantic_vad являются ключевыми отличиями между API Voice Live и API Azure OpenAI Realtime.

Аудиоввод с помощью Azure Speech-to-Text

Azure Speech to Text автоматически активируется при использовании немультимодальной модели, например gpt-4o.

Чтобы явно настроить его, установите model на azure-speech в input_audio_transcription. Это может быть полезно для улучшения качества распознавания для конкретных языковых ситуаций. Чтобы узнать больше о настройке параметров голосового ввода и вывода, см. Как настроить вход и выход данных Voice Live.

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

Аудиовыход через Azure text-to-speech

Параметр можно использовать voice для указания стандартного или настраиваемого голоса. Голос используется для вывода звука.

Объект voice имеет следующие свойства.

См. Как настроить вход и выход Voice Live, чтобы узнать больше о настройке конфигурации голосового вывода.

Стандартные голоса 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, когда возвращаются все сообщения с отметками времени.

Чтобы настроить метки времени звука, можно задать output_audio_timestamp_types в сообщении session.update.

{
    "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

Viseme — это визуальное описание фонемы в разговорном языке. Он определяет положение лица и рта в то время как человек говорит.

Вы можете использовать "стандартный голос Azure" или "пользовательский голос Azure" с animation.outputs установленным на {"viseme_id"}. Служба возвращает response.animation_viseme.delta в ответе и response.animation_viseme.done, когда все сообщения viseme возвращены.

Чтобы настроить 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 отправляется, когда возвращаются все сообщения viseme.

{
    "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 является необязательным. Если этот параметр не указан, служба возвращает серверы ICE для определённого сервера в session.updated ответ. И вам нужно использовать серверы ICE для конкретного сервера для создания локальных кандидатов ICE.

Отправьте SDP клиенту после того, как будут собраны кандидаты ICE.

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

И служба отвечает с помощью SDP сервера.

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

Затем вы можете подключить аватар к SDP сервера.

Связанный контент

• Краткое руководство по API голосовой трансляции
• См. справочник по API голосовой трансляции