Explore a API Azure Voice Live

A API de voz ao vivo permite que os desenvolvedores criem aplicativos habilitados para voz com comunicação bidirecional em tempo real. Esta unidade explora sua arquitetura, configuração e implementação.

Principais recursos da API do Voice Live

A API de voz ao vivo fornece comunicação em tempo real usando conexões WebSocket. Ele suporta recursos avançados, como reconhecimento de fala, síntese de texto para fala, streaming de avatar e processamento de áudio.

• Os eventos formatados em JSON gerenciam conversas, fluxos de áudio e respostas.
• Os eventos são categorizados em eventos de cliente (enviados de cliente para servidor) e eventos de servidor (enviados de servidor para cliente).

As principais funcionalidades incluem:

• Processamento de áudio em tempo real com suporte para vários formatos como PCM16 e G.711.
• Opções de voz avançadas, incluindo vozes OpenAI e vozes personalizadas do Azure.
• Integração de avatar usando WebRTC para vídeo e animação.
• Redução de ruído e de cancelamento de eco integrados.

Para obter uma tabela de modelos e regiões suportados, visite a visão geral da API do Voice Live.

Conectar-se à API do Voice Live

A API ao vivo do Voice suporta dois métodos de autenticação: Microsoft Entra (sem chave) e chave API. O Microsoft Entra utiliza autenticação baseada em token para um recurso do Microsoft Foundry. Você aplica um token de autenticação recuperado usando um Bearer token com o Authorization cabeçalho.

Para a autenticação sem chave recomendada com o Microsoft Entra ID, você precisa atribuir a função Usuário dos Serviços Cognitivos à sua conta de usuário ou a uma identidade gerenciada. Você gera um token usando a CLI do Azure ou SDKs do Azure. O token deve ser gerado com o https://ai.azure.com/.default escopo ou o escopo herdado https://cognitiveservices.azure.com/.default . Use o token no Authorization cabeçalho da solicitação de conexão WebSocket, com o formato Bearer <token>.

Para acesso à chave, uma chave de API pode ser fornecida de duas maneiras. Você pode usar um api-key cabeçalho de conexão na conexão de pré-handshake. Esta opção não está disponível em um ambiente de navegador. Ou, você pode usar um api-key parâmetro de cadeia de caracteres de consulta no URI da solicitação. Os parâmetros da cadeia de caracteres de consulta são criptografados ao usar https/wss.

Ponto de extremidade WebSocket

O ponto de extremidade a ser usado varia dependendo de como você deseja acessar seus recursos. Você pode acessar recursos por meio de uma conexão com o projeto AI Foundry (Agente) ou por meio de uma conexão com o modelo.

• Conexão do projeto: O endpoint é wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01
• Conexão do modelo: O ponto final é wss://<your-ai-foundry-resource-name>.cognitiveservices.azure.com/voice-live/realtime?api-version=2025-10-01.

O ponto final é o mesmo para todos os modelos. A única diferença é o parâmetro de consulta necessário model ou, ao usar o serviço Agente, os agent_id parâmetros e project_id .

Eventos da API do Voice Live

Os eventos de cliente e servidor facilitam a comunicação e o controle dentro da API ao vivo do Voice. Os principais eventos do cliente incluem:

• session.update: Modificar configurações de sessão.
• input_audio_buffer.append: Adicione dados de áudio ao buffer.
• response.create: Gerar respostas através da inferência do modelo.

Os eventos do servidor fornecem comentários e atualizações de status:

• session.updated: Confirme as alterações de configuração da sessão.
• response.done: Indicar a conclusão da geração de respostas.
• conversation.item.created: Notificar quando um novo item de conversa for adicionado.

Para obter uma lista completa de eventos cliente/servidor, visite Referência da API ao vivo do Voice.

Definir configurações de sessão para a API de voz ao vivo

Muitas vezes, o primeiro evento enviado pelo chamador em uma sessão recém-estabelecida da API de Voz ao Vivo é o evento session.update. Esse evento controla um amplo conjunto de comportamento de entrada e saída. As configurações da sessão podem ser atualizadas dinamicamente usando o session.update evento. Os desenvolvedores podem configurar tipos de voz, modalidades, deteção de turnos e formatos de áudio.

Exemplo de configuração:

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

Implemente o processamento de áudio em tempo real com a API de voz ao vivo

O processamento de áudio em tempo real é um recurso central da API de voz ao vivo. Os desenvolvedores podem acrescentar, confirmar e limpar buffers de áudio usando eventos de cliente específicos.

• Acrescentar áudio: Adicione bytes de áudio ao buffer de entrada.
• Confirmar áudio: Processe o buffer de áudio para transcrição ou geração de resposta.
• Áudio claro: Remova os dados de áudio do buffer.

A redução de ruído e o cancelamento de eco podem ser configurados para melhorar a qualidade do áudio. Por exemplo:

{
  "type": "session.update",
  "session": {
    "input_audio_noise_reduction": {
      "type": "azure_deep_noise_suppression"
    },
    "input_audio_echo_cancellation": {
      "type": "server_echo_cancellation"
    }
  }
}

Integre o streaming de avatar usando a API de voz ao vivo

A API de voz ao vivo suporta streaming de avatar baseado em WebRTC para aplicativos interativos. Os desenvolvedores podem definir configurações de vídeo, animação e blendshape.

• Utilize o evento session.avatar.connect para fornecer a oferta SDP do cliente.
• Configure a resolução de vídeo, a taxa de bits e as configurações de codec.
• Defina saídas de animação, como blendshapes e visemes.

Exemplo de configuração:

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