Использование 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=2026-04-10, а для старых ресурсов — wss://<your-ai-foundry-resource-name>.cognitiveservices.azure.com/voice-live/realtime?api-version=2026-04-10. Конечная точка одинакова для всех моделей. Единственное различие заключается в обязательном параметре запроса model или, при использовании службы агента, в параметрах agent_id и project_id.

Например, конечная точка ресурса с личным доменом будет wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2026-04-10&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 и Foundry User вашей учетной записи пользователя или управляемому удостоверению. Роли можно назначить в портале Azure в разделе Контроль доступа (IAM)>Добавить назначение ролей.

  Это важно

  Недавно были переименованы роли RBAC в Foundry. Foundry User, Foundry Owner, Foundry Account Owner и Foundry Project Manager ранее назывались пользователь Azure AI, владелец Azure AI, владелец учетной записи Azure AI и руководитель проекта Azure AI. Пока новое название внедряется, в некоторых местах вы всё ещё можете видеть прежние названия. Идентификаторы ролей и основные разрешения не меняются из-за переименования.

• Создайте токен с помощью 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"},
}

Подавление шума и отмена эхо

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

Отмена эхо на сервере улучшает качество входного звука, удаляя эхо от собственного голоса модели. Таким образом, отмена эхо на стороне клиента не требуется. Подавление эха на сервере полезно, когда синтезированный голос модели воспроизводится пользователю через динамик. Этот процесс помогает избежать ситуации, когда микрофон улавливает голос самой модели.

AEC с опорным сигналом в реальном времени (акустическая эхокомпенсация)

По умолчанию для подавления эха на сервере в качестве опорного сигнала используется собственный внутренний аудиосигнал службы. При использовании Live-Reference AEC клиент вместо этого предоставляет в качестве опорного сигнала аудиосигнал, который он фактически воспроизводит. Эхоподавление по-прежнему доступно в сервисе. Используется предоставленный клиентом опорный сигнал, чтобы отражать фактический путь воспроизведения, включая выход устройства, громкость и любое выполняемое на стороне клиента ресемплирование или микширование.

Используйте Live-Reference AEC, когда звук, который пользователь слышит, отличается от выходных данных необработанной модели. Например, используйте это, когда клиент обрабатывает или микширует аудио перед воспроизведением или когда выход устройства создает эхо, которое не захватывается внутренним опорным сигналом. Этот сценарий распространен в путях воспроизведения на стороне клиента, таких как веб-приложение или мобильное приложение.

Чтобы включить Live-Reference AEC, выполните приведенные действия.

1. Установите input_audio_format на pcm16.
2. В input_audio_echo_cancellation установите для reference_source значение client, а для channels — значение 2.
3. Отправка перемеченного стереофонического звука PCM16. Канал 0 содержит аудиосигнал с микрофона, а канал 1 содержит эталонный аудиосигнал воспроизведения. Для каждой пары образцов сначала отправьте образец, записанный с микрофона, а затем соответствующий эталонный образец воспроизведения.

Поддерживаются только следующие сочетания reference_source и channels:

Невозможно изменить reference_source, channelsinput_audio_formatили input_audio_sampling_rate во время сеанса.

Live-Reference AEC доступна начиная с версии 2026-07-15API.

Ниже приведен пример, который включает Live-Reference AEC:

{
    "type": "session.update",
    "session": {
        "input_audio_format": "pcm16",
        "input_audio_echo_cancellation": {
            "type": "server_echo_cancellation",
            "reference_source": "client",
            "channels": 2
        }
    }
}

Пример для браузера, который захватывает двухканальный звук (микрофон и опорный сигнал воспроизведения) и передаёт его в потоковом режиме в службу, см. в примере Live-Reference AEC.

Улучшения беседы

API Голосовой трансляции предлагает улучшения общения, чтобы обеспечить надежность естественного потока беседы конечных пользователей.

Параметры обнаружения поворота

Обнаружение начала и конца разговора — это процесс, который определяет, когда конечный пользователь начинает или заканчивает говорить. API Voice Live основан на свойстве API turn_detection Azure OpenAI Realtime для настройки обнаружения поворота. Эти типы azure_semantic_vad и azure_multilingual_semantic_vad являются ключевыми отличиями между API Voice Live и API Azure OpenAI Realtime.

Транскрибирование входных звуковых данных

API голосовой трансляции поддерживает несколько моделей транскрибирования для входного звука. Задайте поле model в input_audio_transcription, чтобы выбрать один из вариантов. Доступные модели зависят от используемой модели чата:

Сведения о поддерживаемых языках для каждой модели см. в разделе Поддерживаемые языки Voice Live API.

Azure: распознавание речи

Преобразование речи в текст Azure автоматически включается при использовании немультимодальной модели. Вы можете явно настроить его, задав model значение azure-speech:

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

Параметры настройки ввода речи, такие как список фраз и настраиваемая речь, см. в разделе "Настройка голосовых входных данных и выходных данных".

MAI Transcribe (предварительная версия)

MAI Transcribe — это модель для транскрибирования, которую можно использовать в качестве альтернативы azure-speech с любой текстовой чат-моделью или агентом (например, gpt-4.1). Включите это, установив для input_audio_transcription.model значение mai-transcribe в сообщении session.update:

{
  "type": "session.update",
  "session": {
    "input_audio_transcription": {
      "model": "mai-transcribe"
    },
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful assistant.",
    "turn_detection": {
      "type": "azure_semantic_vad_multilingual"
    }
  }
}

В следующем примере показана та же конфигурация с пакетом SDK voice Live для Python:

from azure.ai.voicelive.aio import connect
from azure.ai.voicelive.models import (
    AudioInputTranscriptionOptions,
    AzureSemanticVadMultilingual,
    AzureStandardVoice,
    Modality,
    RequestSession,
)
from azure.identity.aio import DefaultAzureCredential

async with connect(
    endpoint="https://<your-resource>.services.ai.azure.com/",
    credential=DefaultAzureCredential(),
    model="gpt-4.1",
) as conn:
    await conn.session.update(
        session=RequestSession(
            input_audio_transcription=AudioInputTranscriptionOptions(
                model="mai-transcribe",
            ),
            voice=AzureStandardVoice(name="en-US-AvaNeural"),
            modalities=[Modality.TEXT, Modality.AUDIO],
            instructions="You are a helpful assistant.",
            turn_detection=AzureSemanticVadMultilingual(),
        )
    )

Модели транскрибирования OpenAI

При использовании gpt-realtime или gpt-realtime-miniможно использовать модели транскрибирования OpenAI (whisper-1, , gpt-4o-transcribegpt-4o-mini-transcribeили gpt-4o-transcribe-diarize). Эти модели также поддерживают необязательный prompt параметр для руководства транскрибированием:

{
    "session": {
        "input_audio_transcription": {
            "model": "gpt-4o-transcribe",
            "language": "en",
            "prompt": "Expected terminology: Azure, Foundry, WebSocket"
        }
    }
}

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

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

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

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

Стандартные голоса Azure

MAI-Voice-2-Flash (предварительная версия)

MAI-Voice-2-Flash — это сверхбыстрая выразительная модель синтеза речи с малой задержкой и высоким качеством синтеза, оптимизированная для работы в реальном времени в Voice Live. Ниже приведен пример для голоса MAI-Voice-2-Flash:

{
 "voice": {
   "name": "en-US-Harper:MAI-Voice-2-Flash",
   "type": "azure-standard"
 }
}

Полный список голосов mai-voice-2-flash см. в разделе "Голоса MAI".

нейронный голос Azure

Ниже приведен частичный пример сообщения для стандартной голосовойazure-standard связи:

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

Полный список стандартных голосов см. в разделе "Язык" и "Поддержка голосовой связи" службы "Речь".

Голоса Azure в высоком разрешении (HD)

Вот пример сообщения session.update для стандартного голоса высокой чёткости (HD):

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

Полный список голосов высокой четкости (HD) см. в документации по высокоопределимой (HD) голосовой связи.

Скорость речи

Используйте строковое 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-realtime

Модель azure-realtime — это специализированная модель реального времени, которая использует тщательно подобранный набор встроенных голосов, разработанных для естественно звучащего синтеза речи в реальном времени.

Конфигурация голосовой связи

Укажите голос как структурированный объект, где для type задано значение azure-realtime-native, а для name — одно из поддерживаемых названий голосов:

{
  "type": "session.update",
  "session": {
    "voice": {
      "type": "azure-realtime-native",
      "name": "ava"
    },
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful assistant."
  }
}

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

Поддерживаются следующие azure-realtime-native имена голосов:

Если вы не указываете голос, ava используется по умолчанию. Значение по умолчанию отображается как в ответе session.created , так и в последующих session.updated ответах.

Аватар 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 сервера.

Подробнее см. в этом примере кода использование аватара в Voice Live API.

Использовать фото в качестве аватара

Фотоаватар создает видео с говорящей головой по одному изображению. Voice Live поддерживает как стандартные аватары фотографий (предоставляемые Microsoft), так и пользовательские аватары фотографий (созданные на основе собственного изображения). Чтобы использовать фотоаватар, установите для type значение photo-avatar, а для model — значение базовой модели, на которой он работает (в настоящее время — vasa-1). Для стандартного фотоаватара задайте для character имя персонажа фотоаватара (список см. в разделе Говорящие головы). Для пользовательского фотоаватара задайте для character имя пользовательского фотоаватара, а для customized — значение true.

Стандартный фотоаватар создает видео с говорящей головой на основе одной фотографии, а ожидаемое разрешение исходной фотографии — 512x512.

Прежде чем использовать настраиваемый аватар фотографии, необходимо создать его. Для создания пользовательского фотоаватара требуется фотография человека, а также около одной минуты аудиозаписи с согласием, которая используется, чтобы точнее сопоставить голос с аватаром. Это требование отличается от конфигурации сеанса голосовой трансляции, показанной здесь. Дополнительные сведения см. в разделе "Создание пользовательского аватара фотографии".

Используйте необязательный scene объект для настройки масштаба аватара, положения, поворота и амплитуды перемещения. Значение и диапазоны каждого поля сцены см. в разделе "Настройка сцены аватара" для фото аватара.

Ниже приведен пример avatar объекта для стандартного аватара фотографии:

{
  "session": {
    "avatar": {
      "type": "photo-avatar",
      "model": "vasa-1",
      "character": "anika",
      "video": {
        "codec": "h264",
        "resolution": {
          "width": 1920,
          "height": 1080
        }
      },
      "scene": {
        "zoom": 1.0,
        "position_x": 0.0,
        "position_y": 0.0,
        "rotation_x": 0.0,
        "rotation_y": 0.0,
        "rotation_z": 0.0,
        "amplitude": 0.6
      }
    }
  }
}

Чтобы использовать пользовательский фотоаватар, укажите в character имя пользовательского фотоаватара и задайте для customized значение true:

{
  "session": {
    "avatar": {
      "type": "photo-avatar",
      "model": "vasa-1",
      "character": "your-custom-photo-avatar-name",
      "customized": true
    }
  }
}

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

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