Construa com CometAPIPrecisa de uma API para vários modelos?Teste o fluxo no Playground e depois crie uma chave da API quando o modelo e o custo atenderem ao seu caso de uso.
Conecte-se ao Grok Voice 3.0 com Python, gere uma resposta falada, envie áudio, adicione ferramentas e solucione problemas comuns da API em tempo real.
Deon GoodwinEquipe de pesquisa de modelos e API de IA
Grok Voice 3.0 é o modelo de fala para fala em tempo real da xAI, lançado em 14 de outubro de 2026. O nome do modelo na API é grok-voice-3.0; em 3 de novembro de 2026, grok-voice-latest aponta para essa versão. O anúncio de lançamento lista sessões de voz a US$ 0,08 por minuto (US$ 4,80 por hora). Ele combina conversa, tratamento de interrupções e uso de ferramentas para assistentes de voz e suporte ao cliente. Com Python básico, uma chave de API da xAI e a biblioteca websockets, você pode enviar um prompt e salvar uma resposta falada. Comece com o exemplo abaixo, depois adicione áudio gravado, streaming ao vivo do microfone e ferramentas de negócio conforme seu aplicativo evolui.
Revisado para maior clareza, atribuição de fontes e terminologia de API atual.
Key Takeaways
Grok Voice 3.0 troca fala e texto em tempo real. Seu aplicativo envia e recebe eventos de sessão por WebSocket ao longo de toda a conversa.
Seu primeiro teste pode ser um único turno de texto para áudio. Uma resposta reproduzível confirma que a autenticação e a geração de áudio funcionam antes de você adicionar um microfone.
A entrada de áudio requer um formato correspondente e um limite claro de turno. Seu aplicativo pode enviar áudio PCM gravado com conclusão manual do turno ou transmitir áudio do microfone com detecção de voz no servidor.
Seu aplicativo controla as ações de negócio. Ele valida argumentos de função e permissões do usuário, executa a ação aprovada e retorna o resultado para que o agente de voz continue.
Clientes web e mobile usam credenciais de curta duração. Seu servidor mantém a chave de API permanente e emite tokens temporários para as conexões do cliente.
What Is Grok Voice 3.0?
Grok Voice 3.0 é um modelo de conversação por voz em tempo real desenvolvido pela xAI, operando sob a marca SpaceX Super Intelligence. Ele aceita entrada falada ou em texto e pode retornar áudio e texto dentro de uma sessão contínua. O modelo é otimizado para casos de uso de agentes de voz, em vez de servir como substituto direto para modelos Grok gerais apenas de texto.
Assistentes de voz tradicionais costumam encadear reconhecimento de fala, um modelo de linguagem e síntese de fala. Em vez disso, o Grok Voice expõe uma sessão de fala para fala com comportamento conversacional integrado e suporte a ferramentas. Essa arquitetura pode simplificar a camada de orquestração do desenvolvedor, embora os aplicativos ainda precisem de captura de áudio, transporte, autorização, integrações de negócio e monitoramento.
A definição do modelo Grok Voice 3.0 identifica texto e áudio como suas modalidades de entrada e saída. Para este tutorial, o primeiro ponto de verificação útil é uma resposta reproduzível a partir de um script Python no servidor.
Key Features and Capabilities of Grok Voice 3.0
Manter uma conversa ao vivo: trocar fala e texto via WebSocket ao longo de uma sessão.
Lidar com interrupções: usar detecção de voz no servidor e interromper a reprodução em fila quando o interlocutor começar a falar.
Usar ferramentas de negócio: conectar suas próprias funções para tarefas como consulta de pedidos e agendamento.
Estes são resultados de benchmark publicados, não garantias para a sua implantação. Teste seus próprios sotaques, condições de ruído, ferramentas e caminhos de escalonamento antes de usar o agente com clientes.
What Do You Need Before Calling the Grok Voice 3.0 API?
Crie ou acesse uma conta no xAI Console, gere uma chave de API e verifique se sua conta tem acesso e crédito de uso disponível. Use um terminal local ou um servidor confiável para o exemplo em Python.
Python 3.11 ou posterior e pip disponíveis no mesmo ambiente.
Uma chave de API válida da xAI armazenada como XAI_API_KEY.
Uma conexão de rede que permita conexões WebSocket seguras de saída.
Um player de mídia para abrir o arquivo WAV gerado.
Gere uma chave no xAI Console. Armazene-a em uma variável de ambiente em vez de codificá-la no aplicativo.
Defina a chave de API para o terminal Bash atual.
export XAI_API_KEY="your_xai_api_key"
No Windows PowerShell:
Defina a chave de API para a sessão atual do PowerShell.
$env:XAI_API_KEY="your_xai_api_key"
Instale o cliente WebSocket no seu ambiente Python.
python -m pip install "websockets>=14,<18"
Execute os comandos restantes na mesma sessão de terminal. Se usar um ambiente virtual, ative-o antes de instalar o pacote.
How to Use the Grok Voice 3.0 API with Python
A Realtime API nativa usa uma conexão WebSocket. Diferentemente de conclusões de chat apenas texto, ela troca eventos de sessão contínuos e transmite chunks de áudio enquanto uma conversa está em andamento.
Step 1: Select a fixed model and configure the session
A API aceita um nome de modelo versionado na URL do WebSocket. O exemplo usa grok-voice-3.0 para que a versão solicitada fique explícita. Um evento session.update define a voz, o formato de áudio e o tratamento manual de turno; aguarde session.updated antes de enviar o prompt.
Step 2: Send text and collect the spoken response
Salve o script a seguir como grok_voice_demo.py. Ele envia um único prompt de texto, coleta chunks de áudio codificados em base64 e escreve um arquivo WAV mono, 24 kHz, PCM de 16 bits. Ele também interrompe em erros da API, conclusão sem sucesso ou uma resposta que não produza áudio.
Crie uma resposta falada a partir de um prompt de texto e salve-a como um arquivo WAV.
Após uma resposta bem-sucedida, o terminal imprime Saved grok_response.wav. Abra esse arquivo em um player de mídia e verifique se você ouve uma resposta completa em velocidade normal. Um arquivo ausente ou impossível de reproduzir é motivo para inspecionar os eventos retornados e a configuração de áudio antes de adicionar mais recursos.
A referência de eventos em tempo real descreve o reconhecimento de sessão e o ciclo de vida da resposta usados aqui. O script aguarda o turno inteiro antes de escrever o arquivo; um aplicativo de voz interativo deve reproduzir os chunks de áudio conforme eles chegam.
How Do You Send Audio to Grok Voice 3.0?
Recorded audio with manual turn completion
Este exemplo usa um arquivo WAV mono, 24 kHz, PCM de 16 bits. O Grok Voice 3.0 também oferece suporte a outras taxas de amostragem PCM, μ-law, A-law e Opus. O formato real deve corresponder à configuração em session.update. Substitua apenas o bloco conversation.item.create no script anterior pelo trecho abaixo. Mantenha a chamada response.create a seguir e o loop de recebimento existente.
Substitua o bloco de mensagem de texto por um upload de áudio gravado dentro de main().
with wave.open("request.wav", "rb") as source:
if (
source.getnchannels() != 1
or source.getsampwidth() != 2
or source.getframerate() != SAMPLE_RATE
or source.getcomptype() != "NONE"
):
raise ValueError("Use mono, 24 kHz, 16-bit PCM WAV audio.")
pcm = source.readframes(source.getnframes())
if len(pcm) < SAMPLE_RATE * 2 // 10:
raise ValueError("Use a spoken recording longer than 100 ms.")
for offset in range(0, len(pcm), 4800):
await ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": base64.b64encode(pcm[offset:offset + 4800]).decode("ascii"),
}))
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
while (await receive_event(ws)).get("type") != "input_audio_buffer.committed":
pass
Indente essa substituição no mesmo nível do bloco original de mensagem de texto, dentro do contexto do WebSocket. Ela envia amostras PCM brutas do arquivo WAV, não o cabeçalho do contêiner WAV. O primeiro script seleciona explicitamente o modo manual de turno, portanto confirmar o buffer e depois solicitar uma resposta são ações separadas.
Live microphone capture and immediate playback
Para uma conversa interativa, capture áudio continuamente, converta-o para o formato de entrada configurado e envie chunks curtos enquanto um loop de recebimento separado trata as respostas. Selecione server_vad para detecção automática de turnos, em vez do modo manual usado no exemplo de arquivo gravado. Evite adicionar uma segunda response.create quando o servidor já estiver criando a resposta.
Em caso de interrupção, pare rapidamente a reprodução em fila do assistente. Somente o cancelamento de rede não remove o áudio já armazenado em buffer pelo seu aplicativo. Mantenha a fila de reprodução pequena e acompanhe quanto áudio o ouvinte de fato escutou para que seu aplicativo mantenha o estado da conversa consistente.
How to Add Tools to a Grok Voice 3.0 Agent?
Os aplicativos podem expor ferramentas como consulta de pedidos, agendamento ou verificação de conta. O agente pode interpretar uma solicitação falada complexa, chamar uma função autorizada e usar o resultado para continuar. Isso é particularmente útil quando um cliente solicita várias alterações relacionadas em uma única chamada.
A API oferece suporte a funções personalizadas e ferramentas gerenciadas pelo servidor. Para uma função personalizada, seu aplicativo implementa a ação; definir uma ferramenta não conecta por si só o modelo ao seu banco de dados.
Declare o nome da função, a descrição e o esquema de argumentos JSON em session.tools.
Trate response.function_call_arguments.done, analise os argumentos e valide a permissão do solicitante antes de executar a função.
Retorne o resultado como um evento conversation.item.create com item.type definido como function_call_output e o call_id correspondente.
Envie response.create após os resultados das funções necessárias terem sido enviados. Se várias chamadas chegarem juntas, retorne todos os seus resultados antes de pedir ao modelo para continuar.
Comece com uma ferramenta somente leitura, como verificar o status de entrega de um pedido. Para ações que alteram reservas, emitem reembolsos ou fazem pedidos, imponha verificações de identidade, confirmação e proteção contra solicitações duplicadas no aplicativo.
How to Use Grok Voice 3.0 in Browser and Mobile Apps
Use credenciais efêmeras para conexões do lado do cliente. Seu servidor solicita um token de curta duração com sua chave de API permanente e passa o token para o cliente. Autentique as solicitações ao seu próprio endpoint de token e aplique limites de uso para que ele não se torne um gateway irrestrito.
Mantenha o consentimento do microfone, os controles de gravação e o status da conexão visíveis na interface. Trate a perda de conexão explicitamente: interrompa reproduções antigas, informe ao usuário que a conexão está se recuperando e evite repetir ações que já possam ter sido concluídas.
How to Troubleshoot Common Grok Voice 3.0 API Errors
Falha de autenticação: confirme que XAI_API_KEY está definido no terminal que executa o script e que a chave pertence a uma conta com acesso. Não cole a chave em logs ou mensagens de suporte.
Argumentos inesperados da biblioteca cliente: verifique se o pip instalou a versão solicitada de websockets no ambiente Python usado para executar o script.
Sem saída de áudio: inspecione eventos de erro e response.done, confirme que session.updated reconheceu a configuração e verifique se uma resposta foi solicitada para o turno manual.
Reprodução distorcida: compare os bytes reais com o codec, taxa de amostragem, contagem de canais e cabeçalho WAV configurados. Renomear um arquivo MP3 para WAV não o converte.
Timeout: verifique o acesso de rede e o status do serviço, depois inspecione o último evento bem-sucedido. Tente novamente uma conexão com falha separadamente de qualquer ação de negócio que já possa ter sido executada.
What Should You Budget for Grok Voice 3.0 API Calls?
O uso de voz e integrações personalizadas podem gerar cobranças separadas. Para este tutorial, as tarifas publicadas relevantes são a sessão em tempo real e entradas de texto; produtos independentes de transcrição e geração de fala são serviços separados.
Sessão de fala para fala: US$ 0,08 por minuto, equivalente a US$ 4,80 por hora.
Entrada de texto durante uma sessão de voz: US$ 0,004 por entrada de texto.
Tarifas conferidas em 29 de outubro de 2026. Consulte a página oficial de preços para valores atuais.
Por exemplo, 500 minutos faturáveis de sessão correspondem a US$ 40 em cobranças básicas de voz. Essa estimativa exclui entradas de texto, ferramentas opcionais, telefonia e sua própria infraestrutura. Comece com sessões de teste curtas e feche conexões ociosas quando a conversa terminar.
Conclusion
Comece com um turno completo da API Grok Voice 3.0: conecte, configure a sessão, envie um prompt, receba o áudio e reproduza o resultado. Quando esse caminho funcionar, adicione fala gravada, depois construa a captura do microfone e o streaming de reprodução ao redor disso. Introduza ferramentas de negócio somente depois que os caminhos de conversa e tratamento de erros estiverem confiáveis.
