Explorar a API do Azure Voice Live

A API dinâmica do Voice 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 ao vivo do Voice fornece comunicação em tempo real usando conexões WebSocket. Ele dá suporte a recursos avançados, como reconhecimento de fala, síntese de texto em fala, streaming de avatar e processamento de áudio.

• Eventos formatados por 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).

Os principais recursos 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 integrada e cancelamento de eco.

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

Conectar-se à API do Voice Live

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

Para a autenticação sem chave recomendada com a ID do Microsoft Entra, você precisa atribuir a função de 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 os SDKs do Azure. O token deve ser gerado com o escopo https://ai.azure.com/.default 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 cabeçalho de conexão api-key na conexão pré-handshake. Essa 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 do 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 do AI Foundry (Agent) ou por meio de uma conexão com o modelo.

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

O ponto de extremidade é 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 parâmetros agent_id e project_id.

Eventos da API do Voice Live

Eventos de cliente e servidor facilitam a comunicação e o controle dentro da API dinâmica do Voice. Os principais eventos do cliente incluem:

• session.update: modifique as configurações de sessão.
• input_audio_buffer.append: adicione dados de áudio ao buffer.
• response.create: gere respostas por meio de inferência de 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: indique a conclusão da geração de resposta.
• conversation.item.created: notifique quando um novo item de conversa for adicionado.

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

Definir as configurações de sessão para a API dinâmica do Voice

Geralmente, o primeiro evento enviado pelo chamador em uma sessão recém-estabelecida da Voice Live API é o evento session.update. Esse evento controla um amplo conjunto de comportamentos de entrada e saída. As configurações de sessão podem ser atualizadas dinamicamente usando o session.update evento. Os desenvolvedores podem configurar tipos de voz, modalidades, detecçã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"
  }
}

Implementar o processamento de áudio em tempo real com a API ao vivo do Voice

O processamento de áudio em tempo real é um recurso principal da API ao vivo do Voice. 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.
• Limpar áudio: 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"
    }
  }
}

Integrar o streaming de avatar usando a API ao vivo do Voice

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

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

Exemplo de configuração:

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