Grok Text to Speech
Sign in

Grok Voice 3.0 API Session Builder: session.update Config and Code

Pick a voice, prompt, tools and audio format and get a ready-to-run Grok Voice 3.0 session.update config with Python, Node.js and browser (ephemeral token) code. Checked against xAI’s documented limits.

Runs in your browser. Nothing you enter is uploaded.

Agent

grok-voice-latest is an alias for grok-voice-3.0; pin grok-voice-3.0 in production.

xAI recommends five ## sections in this order, written in the second person. Build one with the prompt generator.

turn_detection.idle_timeout_ms: the agent speaks up again if the user stays quiet this long after a reply.

Sent as a force_message, spoken word for word without the model.

Audio

PCM 24 kHz is the default and is left out of the config. Use G.711 μ-law or A-law for phone audio.

Language and pronunciation

Names the model should hear correctly. Up to 100 terms, 50 characters each, comma separated.

One per line: written phrase => how to say it. Changes the audio, not the transcript.

Tools
# pip install websockets
import asyncio
import json
import os

import websockets

URL = "wss://api.x.ai/v1/realtime?model=grok-voice-latest"

SESSION_UPDATE = {
    "type": "session.update",
    "session": {
        "voice": "eve",
        "instructions": """## Role & Persona
You are a friendly, professional support agent for Acme Internet.

## Objective
Answer customer questions and solve simple account issues, or offer to transfer to a human when you cannot.

## Conversation Flow
Find out what the caller needs with one short question, answer it, then ask if there is anything else.

## Guardrails & Escalation
Stay within Acme products and services. Say you don't know rather than guessing.

## Voice & Communication Style
Speak naturally in 1–2 short sentences per turn. No markdown, lists or emojis.""",
        "turn_detection": {
            "type": "server_vad",
        },
    },
}


async def main():
    async with websockets.connect(
        URL,
        additional_headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
    ) as ws:
        await ws.send(json.dumps(SESSION_UPDATE))

        async for message in ws:
            event = json.loads(message)
            if event["type"] == "response.output_audio.delta":
                pass  # base64 audio in event["delta"]: decode and play it
            else:
                print(event["type"])


asyncio.run(main())

Field names and limits from xAI's speech to speech docs as of 2026-10-19. Defaults are left out, so the config stays short.

To start a Grok Voice 3.0 agent you open a WebSocket to wss://api.x.ai/v1/realtime?model=grok-voice-latest and send one session.update event with the voice, the system prompt and the tools. The builder above writes that event and the code around it from the options you pick, leaves out every setting that is already the default, and warns when a value breaks one of xAI's documented limits.

What the builder covers

Every field maps to a parameter in xAI's speech to speech docs (read 19 Oct 2026):

Option in the builderParameterNotes
Model?model= on the URLgrok-voice-latest is an alias for grok-voice-3.0; grok-voice-2.0 is deprecated
Voicevoiceany of the 28 built-in voices or a custom voice ID
Instructionsinstructionsthe system prompt
Reasoning effortreasoning.efforthigh (default) or none
Turn detectionturn_detection.typeserver_vad for automatic turns, null for manual turns
Re-engage after silenceturn_detection.idle_timeout_msthe agent speaks again if the user stays silent
Codec and sample rateaudio.input.format, audio.output.formatPCM at 8–48 kHz (24 kHz default), G.711 μ-law / A-law at 8 kHz, Opus at 24 kHz
Speaking speedaudio.output.speed0.7 to 1.5, default 1.0
Language hintaudio.input.transcription.language_hintBCP-47 code; Spanish and Portuguese need the regional variant
Key termsaudio.input.transcription.keytermsup to 100 terms, 50 characters each
Pronunciation fixesreplacechanges what is spoken, not the transcript
Toolstoolsweb_search (up to 5 domains), x_search (up to 20 handles), file_search, mcp, function
Session resumptionresumption.enabledreplays earlier turns on reconnect; history expires after 30 minutes idle
Opening lineforce_message itemspoken word for word, no response.create needed

Which code tab to use

  • Python and Node.js connect with your API key in the Authorization header. Use them on a server, for phone bridges, or to test a prompt from your terminal.
  • Browser is two pieces. Your server calls POST /v1/realtime/client_secrets to mint a short-lived token (10 minutes by default, 1 hour at most) and the page connects with it as a WebSocket subprotocol, xai-client-secret.<token>, because browsers cannot set WebSocket headers. Your API key never reaches the page.
  • JSON is the raw event, for when you already have a client, such as an OpenAI Realtime client pointed at xAI's URL.

The code stops where your app starts: it sends the config and prints events, but microphone capture and audio playback depend on your platform. xAI's cookbook has full web, WebRTC, iOS and Twilio phone examples.

Choosing settings

  • Reasoning. Leave high on for agents that look things up, follow multi-step policies or handle unclear requests. Try none for simple, scripted flows where every bit of latency counts. The price per minute is the same either way.
  • Audio format. For browser and app audio, keep the 24 kHz PCM default and match it on both sides to avoid resampling. For phone audio over SIP or a telephony provider, pick G.711 μ-law (North America, Japan) or A-law (most other countries) so nothing has to be transcoded.
  • Tools. Only switch on tools the prompt actually uses, and only name tools in the prompt that are switched on. xAI's prompting guide says a mismatch either way makes the agent worse; the builder warns if your instructions mention web_search, x_search or file_search while that tool is off.
  • Pin the model once you go live. grok-voice-latest will move to newer models; grok-voice-3.0 will not.

Related tools

The Grok Voice 3.0 prompt generator writes the instructions in xAI's recommended five-section shape, and the Grok Voice 3.0 cost calculator turns your expected call volume into a monthly bill. To pick a voice by ear, try them in the free Grok text to speech tool: the voices are the same in text to speech and in voice agents. For background on the model, read the Grok Voice 3.0 guide and the Grok voice agent guide.

Last updated:

Questions

More Grok voice tools

Grok Voice 3.0 prompt generatorWrite a Grok Voice 3.0 system prompt in the five-section shape xAI recommends: role, objective, conversation flow, guardrails and voice style, plus facts, escalation and a safety path. Free, in your browser.OpenGrok Voice 3.0 cost calculatorWork out what a Grok Voice 3.0 agent costs: calls, minutes per call, text inputs and web searches in, cost per call, per 1,000 calls, per month and per year out. Uses xAI’s $0.08 per minute list price.OpenGrok text to speechTurn text into natural speech with the real Grok voices. 28 voices, 20 languages, speech tags for pauses, laughs and whispers. Try it free without an account; sign in with Google for longer clips and MP3 downloads.OpenGrok Voice API pricing calculatorThe xAI Grok text to speech API costs $15 per 1M characters, 62.5% to 81% less than ElevenLabs ($40 or $80) and the same as OpenAI tts-1 (list prices, 17 Oct 2026). Plus Grok Voice 3.0 and transcription prices and a calculator.Open