Grok Voice Think Fast 2.0 API-handledning: Bygg en röstagent i realtid i Python

SpaceXAI:s Grok Voice Think Fast 2.0 är en speech-to-speech-modell. Du skickar ljud över en WebSocket och får ljud tillbaka, och däremellan kan modellen resonera och fortsätta tala medan ett funktionsanrop den beslutat att göra redan körs. Inget separat steg för tal-till-text, inget separat steg för text-till-tal.

SpaceXAI annonserade Think Fast 2.0 den 29 juli 2026: snabbare första ljudbit, stabilare full duplex-beteende (lyssnar medan den talar i stället för att strikt ta turer) och verktygsanrop som triggar tidigt i turen. Jag håller benchmarkdelen kort, för i en handledning är det viktigaste vad som ändras i din kod.

Vi ska bygga en kundtjänst-agent för en webbutik. En uppringare kan fråga om en order, ändra en leveransinstruktion, avbryta, avbryta agenten mitt i en mening och plocka upp samtalet igen efter ett tappat uppkopplingsförsök. Detta är API-vägen, inte det no-code-verktyg som vår handledning för Grok Voice Agent Builder går igenom. Börja där för konsolversionen.

Vad är Grok Voice Think Fast 2.0?

Grok Voice Think Fast 2.0 är SpaceXAI:s senaste modell för Speech to Speech API, produktnamnet bakom det de flesta bara kallar Grok Voice. Om du fortfarande tänker på företaget som xAI: samma gäng – det slogs in i SpaceX och bytte namn till SpaceXAI den 6 juli 2026. API:t följde inte rebrandingen, så varje identifierare nedan säger fortfarande xai, från variabeln XAI_API_KEY till värden api.x.ai.

En traditionell röststack kedjar tre tjänster: tal-till-text, en språkmodell och sedan text-till-tal, och varje hopp adderar latens och en plats där kontext kan gå förlorad. Think Fast 2.0 kollapsar detta till en modell som tar ljud eller text in och producerar ljud eller text ut över samma uppkoppling.

Speech-to-speech-WebSocket jämfört med pipelinearkitektur med tre tjänster. Bild av författaren.

För en agent som agerar i stället för att bara prata är det avgörande att resonemang och tal körs parallellt. SpaceXAI säger att verktygsanrop "vanligtvis" börjar exekvera innan agenten avslutar sin första mening, och det ordet gör faktisk skillnad.

På benchmarksen SpaceXAI hänvisar till från Artificial Analysis får Think Fast 2.0 82,9 % på Speech to Speech Index mot 75,7 % för 1.0, och kapar tiden till första ljud från 1,25 sekunder till 0,70 sekunder. Leverantörssiffror på ett allmänt benchmark är en hypotes om ditt samtalsflöde, inte en testplan.

Det finns tre modellsträngar du kommer att se: grok-voice-latest, grok-voice-think-fast-2.0 och grok-voice-think-fast-1.0. Aliaset är bekvämt under prototypande och inte tillräckligt stabilt för något annat.

När jag testade den 4 augusti 2026 löstes grok-voice-latest fortfarande upp till grok-voice-think-fast-1.0, med SpaceXAI:s releasenotiser som lade flytten till Think Fast 2.0 till nästa dag. Den växlingen är lika mycket en prisändring som en modelländring, 0,08 USD per minut ljud mot 0,05 USD för 1.0, så ett opinnat alias blir dyrare utan att en rad i din kod ändras. Fäst den versionsmärkta strängen i allt du driftsätter.

Vad vi ska bygga

Agenten täcker det en supportlinje brukar få: slå upp en order, hitta en via e-post när uppringaren saknar nummer, ändra en leveransinstruktion, avbryta, öppna eller kolla ett ärende och lämna över samtalet till en person. Avbrott och tappad uppkoppling dyker upp längs vägen.

Det är en handfull små filer i stället för ett skript, eftersom varje del har ett annat jobb och du vill kunna testa dem separat. Här är strukturen:

• config.py laddar API-nyckeln och innehåller modellsträngen, samplingsfrekvensen och slutpunkt-URL:erna

• voice_client.py omsluter WebSocketen, spårar debitering och exponerar hjälpmetoder för skicka/ta emot

• tools.py definierar orderfunktionerna och ett litet in-memory-orderlager i stället för en riktig databas

• assistant.py innehåller systemprompten, sessionskonfigurationen och händelseslingan som knyter ihop allt

• token_server.py är en liten FastAPI-slutpunkt som myntar kortlivade token

• app_streamlit.py lägger samma klient bakom ett live-samtal i webbläsaren, som jag återkommer till efter testavsnittet

Lärandebanan körs från en terminal. Demon lägger till mikrofonen.

Förutsättningar

Du behöver ett SpaceXAI-konto med en API-nyckel, en finansierad betalningslösning (det finns ingen permanent gratisnivå, och promotekrediter för nya konton räcker inte), och tillräcklig bekantskap med asyncio och WebSockets för att kunna följa utan en rad-för-rad-förklaring av await.

SpaceXAI:s quickstart-exempel använder det rena paketet websockets i stället för ett dedikerat SDK, och det gör vi också. Dokumentationen anger aldrig en krävd Pythonversion. Jag testade på 3.11.

Behåll API-nyckeln på servern. Om en webbläsare eller mobilapp pratar direkt med Voice API får den en kortlivad token i stället för din riktiga nyckel, vilket täcks i säkerhetsavsnittet nedan.

Sätta upp projektet

Varje fil nedan finns i projektets repo, så du kan klona det i stället för att kopiera utdrag:

git clone https://github.com/KhalidAbdelaty/grok-voice-think-fast-2.0.git
cd grok-voice-think-fast-2.0
pip install -r requirements.txt

websockets bär realtidsuppkopplingen och python-dotenv läser in din nyckel. Resten täcker token-slutpunkten och webbläsardemon. Lägg din nyckel i .env:

XAI_API_KEY=xai-your-key-here

Det är det mesta av uppsättningen. Anslutningen är den intressanta delen.

Förstå Grok Voice Realtime API

Grok Voice är produktnamnet. Det du faktiskt skriver kod mot är en WebSocket-slutpunkt på wss://api.x.ai/v1/realtime, och hela konversationen sker som en ström av JSON-händelser över just den socketen.

Händelselivscykeln

En anslutning följer en fast form: servern skickar session.created och conversation.created så snart du ansluter, du skickar session.update för att konfigurera röst och verktyg, servern bekräftar med session.updated, och därifrån skapar du konversationsobjekt och begär svar. Jag körde detta mot en live-nyckel och ordningen matchade dokumenten exakt.

• session.update (klient) konfigurerar röst, instruktioner, verktyg och ljudformat

• conversation.item.create (klient) lägger till ett användarmeddelande, ett assistentmeddelande eller ett verktygsresultat

• response.create (klient) ber modellen att tala; serverns VAD skickar detta åt dig automatiskt

• response.output_audio.delta och response.output_audio_transcript.delta (server) strömmar svaret medan det genereras

• response.done (server) avslutar turen

Två saker snubblar folk på. Sidan för Speech to Speech-dokumentationen jag länkade ovan nämner en conversation.item.created-händelse under återupptagning av session, men den kanoniska händelsereferensen listar bara conversation.item.added, och det var vad som kom fram i varje test jag körde, så koda mot den. Du kommer också att se en odokumenterad ping -händelse några sekunder in i de flesta uppkopplingar, nämnd bara så att du inte tolkar den som ett fel.

Ljudformat och transport

Codec och transport är separata val. Codecen, satt under audio.input.format och audio.output.format, är audio/pcm (Linear16, standard 24000 Hz), audio/pcmu eller audio/pcma (G.711 på 8 kHz, för telefoni), eller audio/opus (24 kHz). Transport är hur dessa byte färdas på linan:

• json (standard) skickar ljud som base64-text inuti input_audio_buffer.append och response.output_audio.delta, lätt att logga och felsöka

• binary skickar råa codec-byte som binära WebSocket-ramar, hoppar över base64-overhead på bekostnad av en mottagningsslinga som måste grena på meddelandetyp

Börja med JSON. Varje exempel i dokumentationen använder det, det är trivialt att inspektera och base64-overhead är inte vad som flaskhalsar en supportagent. Gå över till binärt om du mäter en anledning.

Kompatibilitet med OpenAIs Realtime API

Hoppa vidare om du aldrig rört OpenAIs Realtime API. För alla andra följer Speech to Speech API:t OpenAI Realtime API tillräckligt nära för att de flesta klienter kan portas genom att byta bas-URL och nyckel, men det är inte en perfekt drop-in.

Transkript kommer som conversation.item.input_audio_transcription.updated här i stället för OpenAIs delta, några OpenAI-händelser saknar stöd, och SpaceXAI lägger till egna tillägg: force_message för en skriptad informationsrad, resumption för återanslutningar, och replace för att rätta feluttalade varumärken före text-till-tal.

Bygga röstagenten i realtid

Nog med protokoll. Här är klienten som pratar med det.

Ansluta och konfigurera sessionen

Anslutningen öppnas med en bearer-token och en modell-parameter, och det första meddelandet du skickar konfigurerar allt kring hur agenten beter sig:

import asyncio
import json
import os
import websockets

MODEL = "grok-voice-think-fast-2.0"  # pin the version, not grok-voice-latest

async def connect():
    url = f"wss://api.x.ai/v1/realtime?model={MODEL}"
    ws = await websockets.connect(
        url, additional_headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"}
    )
    await ws.send(json.dumps({
        "type": "session.update",
        "session": {
            "voice": "eve",
            "instructions": SYSTEM_PROMPT,
            "turn_detection": {"type": "server_vad"},
            "tools": ORDER_TOOLS,
            "resumption": {"enabled": True},
        }
    }))

return ws

instructions är systemprompten, och den här modellen vill ha korta sådana. SpaceXAI:s migrationsnotiser säger att man ska förenkla prompts skrivna för äldre GPT-erans röstmodeller i stället för att porta dem rakt av. Min säger åt agenten att hålla svaren korta, ställa en fråga i taget och läsa upp varje skrivning tillbaka före åtgärd. En talad bekräftelse är en UX-finess, inte en säkerhetskontroll. Din applikation upprätthåller fortfarande behörigheter på själva skrivningen.

En sak som överraskade mig: en okänd modellsträng ger inte fel vid anslutning, den faller tyst tillbaka till grok-voice-think-fast-1.0. Att nedgradera en betald förfrågan på grund av ett stavfel, utan att säga det, är ett märkligt standardläge. Logga fältet session.model i session.created en gång vid uppstart och kontrollera att du fick det du bad om.

Terminalutskrift som visar session.created efter anslutning. Bild av författaren.

Strömma användarljud

Med turn_detection.type satt till server_vad behöver du bara fortsätta lägga till ljud. Servern avgör när uppringaren slutat prata och triggar svaret åt dig. Sätt den till null i stället så äger du själv det beslutet, och skickar bufferten explicit när du anser att turen är över.

async def send_audio_chunk(ws, pcm_bytes: bytes):
    await ws.send(json.dumps({
        "type": "input_audio_buffer.append",
        "audio": base64.b64encode(pcm_bytes).decode(),
    }))

Server-VAD har tre rattar, och att ställa dem fel är det vanligaste sättet jag har sett en röstagent kännas trasig samtidigt som inget i loggarna felade. Inga av dem dyker upp i session.updateds eko som standard, så jämför mot dokumentationen i stället för att anta.

• threshold (0,1 till 0,9, standard 0,85), hur högt ljud måste vara för att räknas som tal; höj i bullriga rum, sänk om tysta talare missas

• silence_duration_ms, hur länge uppringaren blir tyst innan servern avslutar deras tur; för kort kapar folk mitt i tanken, för långsamt känns segt

• prefix_padding_ms (standard 333), en skiva ljud bevarad precis innan tal upptäcktes, så att första stavelsen inte klipps

Justera silence_duration_ms först om uppringare blir avklippta när de pausar för att tänka. Det är den jag tar till innan jag rör de andra två.

Ta emot och spela upp svaret

Ljud kommer i små bitar som response.output_audio.delta, och poängen med strömning är att du spelar varje bit i samma ögonblick den landar i stället för att vänta på response.done.

async def play_response(ws):
    async for message in ws:
        event = json.loads(message)
        if event["type"] == "response.output_audio.delta":
            chunk = base64.b64decode(event["delta"])
            speaker.write(chunk)  # your playback call goes here
        elif event["type"] == "response.output_audio_transcript.delta":
            print(event["delta"], end="", flush=True)

Behåll transkriptet även i produktion. Det är det billigaste felsökningsverktyget du har när en uppringare säger att agenten "sa något konstigt".

Lägga till verktyg i röstagenten

En röstagent som bara pratar är en chatbot med mikrofon.

Skapa orderverktygen

Varje verktyg är ett JSON-schema plus en enkel Python-funktion på vår sida. Modellen rör aldrig databasen, den ser bara vad vår funktion returnerar.

ORDER_TOOLS = [
    {
        "type": "function",
        "name": "check_order_status",
        "description": "Look up the status, ETA, and delivery instructions for an order.",
        "parameters": {
            "type": "object",
            "properties": {
                "order_number": {"type": "string", "description": "e.g. ORD-1042"},
            },
            "required": ["order_number"],
        },
    },
    # find_orders, update_delivery_instructions, cancel_order,
    # create_support_ticket, check_ticket_status and transfer_to_human
    # all follow the same shape
]

Läsoperationer som check_order_status är säkra att försöka igen om något time:ar ut. Skrivoperationer är det inte: att försöka update_delivery_instructions igen efter ett tvetydigt timeout kan tillämpa samma ändring två gånger. En bekräftelserad i prompten stoppar inte det, så ge skrivningar en idempotency-nyckel eller en duplicatkontroll i stället.

Lägg in vägran i funktionen också. cancel_order returnerar en anledning och ett alternativ i stället för att avbryta en skickad order, för en prompt som säger "avbryt aldrig skickade orders" är ett förslag – och en funktion som vägrar är det inte.

Hantera loopen för verktygsanrop

Fyra steg, och ordningen är viktigare än den ser ut. Modellen skickar response.function_call_arguments.done, din kod kör funktionen, du skickar tillbaka resultatet som ett function_call_output -objekt, och först därefter ber du modellen fortsätta.

async def handle_tool_call(ws, event):
    args = json.loads(event["arguments"])
    result = execute(event["name"], args)  # never raises; errors come back as {"error": ...}
    await ws.send(json.dumps({
        "type": "conversation.item.create",
        "item": {
            "type": "function_call_output",
            "call_id": event["call_id"],
            "output": json.dumps(result),
        },
    }))

Om modellen behöver mer än ett verktyg för en begäran avfyrar den flera function_call_arguments.done innan något ljud spelas. Lös alla och skicka varje resultat innan ett enda response.create. Skickar du det för tidigt svarar modellen utan kontexten från anropen som fortfarande pågår.

Det finns en fallgrop här som SpaceXAI dokumenterar och som jag ändå stötte på första gången: att skicka response.create i samma ögonblick som ditt verktygsresultat går ut kan överlappa med den inledande meningen agenten fortfarande spelar upp. I en körning öppnade den med "Jag ska kolla status på order ORD-1042 direkt" och kallade verktyget mitt i meningen, så ett omedelbart svar hade talat över sin egen öppning.

Vänta tills den aktuella turens ljud är klart och visa ett kort "tänker"-läge under tiden.

Flöde för verktygsanrop innan svaret fortsätter. Bild av författaren.

Hantera avbrott och konversationsstatus

Två separata problem här. En uppringare pratar över agenten mitt i ett svar, och en WebSocket droppar och behöver plockas upp igen.

Stöd för naturliga avbrott

Med server_vad på är barge-in automatiskt på serversidan: i samma ögonblick som den upptäcker att uppringaren talar igen, signalerar den input_audio_buffer.speech_started och slutar generera det gamla svaret. Ditt jobb är klienthalvan av den handskakningen: rensa vad som redan ligger i kön för uppspelning så att agenten tystnar i stället för att avsluta en mening ingen bad om att höra.

if event["type"] == "input_audio_buffer.speech_started":
    playback_queue.clear()

För manuella, icke-VAD-sessioner gör response.cancel samma jobb på begäran. Det finns också conversation.item.truncate för att trimma ett assistentobjekt ner till vad som faktiskt hördes. Dokumentationen bekräftar att den finns men inte när den ska avfyras under en live barge-in, så testa timingen själv.

Jag testade detta med en ändring av leveransinstruktion mitt i svaret: starta begäran, avbryt med en annan adressdel halvvägs genom agentens bekräftelse. Det som räknas är om agenten tillämpar den korrigerade instruktionen i stället för att tyst avsluta den gamla, inte om ljudet stoppade. Verifiera mot orderposten, inte mot tystnaden. Webbläsardemon i slutet låter dig höra detta.

Återuppta en frånkopplad session

Återupptagning av session är opt-in och det är inte minne. Sätt resumption.enabled: true på session.update, fånga ID:t från händelsen conversation.created, och om socketen droppar, återanslut med ?conversation_id=<id> i URL:en och välj in igen på den nya anslutningen.

async def reconnect(conversation_id):
    url = f"wss://api.x.ai/v1/realtime?model={MODEL}&conversation_id={conversation_id}"
    ws = await websockets.connect(url, additional_headers=auth_header)
    await ws.send(json.dumps({"type": "session.update", "session": {"resumption": {"enabled": True}}}))
    return ws

De cachade turerna, transkripten, verktygsanropen och verktygsresultaten spelas upp innan din nästa fråga, och cachen försvinner efter 30 minuters inaktivitet. Jag testade genom att fråga om en order, tappa uppkopplingen och återansluta för en uppföljning utan att upprepa mig; agenten plockade upp ETA:n korrekt.

En odokumenterad hake: uppspelningen landar inte direkt, så en fråga som avfyras i samma ögonblick som socketen öppnas kan gå före och komma tillbaka utan minne av den tidigare turen. Ge det en sekund innan du skyller på återupptagning.

Terminallogg av en återupptagen session. Bild av författaren.

Använd inte detta i stället för att spara orderstatus i din egen databas. Om cachen löper ut eller uppringaren ringer tillbaka i morgon börjar du från noll kontext, och det är avsiktligt.

Säkra och övervaka agenten

Lägg aldrig en permanent API-nyckel i webbläsar- eller mobilkod. Om en klient ansluter direkt i stället för via din server, mynta en kortlivad token:

from fastapi import FastAPI
import httpx, os

app = FastAPI()

@app.post("/session")
async def create_session():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.x.ai/v1/realtime/client_secrets",
            headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
            json={"expires_after": {"seconds": 300}},
        )
    return response.json()  # {"value": "xai-realtime-client-secret-...", "expires_at": ...}

En webbläsare kan inte sätta en anpassad Authorization -header på en WebSocket-handshake, så den skickar token via headern sec-websocket-protocol i stället, med prefixet xai-client-secret..

Server myntar token, webbläsare ansluter till samtal. Bild av författaren.

Debiteringen körs på två mätare. Ljud, skickat eller mottaget, debiteras med 0,08 USD per minut som jag nämnde tidigare, vilket är 4,80 USD per timme, och varje conversation.item.create som inte är ljud och inte är ett function_call_output kostar en fast 0,004 USD. response.create debiteras inte alls. Varje response.done bär ett usage-objekt, som i mitt test rapporterade output_audio_seconds tillsammans med ett separat billable_audio_seconds. Debittera utifrån dessa, inte utifrån uppskattningar.

Dokumenterade gränser på Speech to Speech API är 10 samtidiga sessioner per team och ett 120-minuters sessionslock, båda i us-east-1. Planera inte kapacitet utifrån Voice Agent API:s siffror, som är annorlunda.

Var exakt kring integritet. SpaceXAI:s säkerhets-FAQ säger att API-förfrågningar och svar lagras krypterade i 30 dagar för missbruksövervakning och inte används för träning utan tillstånd, och att team kan slå på Zero Data Retention, även om ZDR tar bort ihågkommen konversationshistorik för röstagenten och därför inte fungerar med återupptagning.

Om du informerar om att ett samtal spelas in eller hanteras av AI är det vad tillägget force_message jag listade tidigare är till för. Raden spelas upp exakt som skriven i stället för vad modellen skulle parafrasera den till.

Testa röstagenten

En 200-status på WebSocket-handshaken säger ingenting om huruvida agenten gjorde rätt sak. Testa utfallet, inte bara uppkopplingen.

• Ett rent orderuppslag, där du stämmer av det upplästa svaret mot posten, inte bara att ett svar kom
• Ett avbrutet svar, där du bekräftar att uppspelningen stoppar och att agenten adresserar den nya begäran
• En leveransuppdatering som kräver bekräftelse, kontrollerad mot orderposten
• En vägran, som att avbryta en skickad order, där agenten måste förklara regeln i stället för att be om ursäkt
• Ett okänt ordernummer, och se till att agenten säger det i stället för att hitta på en status
• Ett verktyg som returnerar ett fel, där du kontrollerar att agenten säger det i stället för att fastna
• Återanslutning och återupptagning, inklusive det uppspelningsfönster jag nämnde tidigare
• Brusigt ljud, snabbt tal och en uppringare som bokstaverar nummer och adresser

Jag körde de flesta av dessa mot en live-nyckel medan jag skrev det här. De intressanta felen var beteendemässiga, inte fel: tajmingen för återupptagning ovan, och en VAD-tröskel utanför intervallet som accepterades i stället för att avvisas, den typen av saker som skeppas tyst trasigt om du bara testar glada vägen. Lägg till ett flerspråkigt test också, och se FAQ:erna för en knorr i hur du anger språk.

Två av dessa kan du inte testa genom att skriva. app_streamlit.py är en Streamlit-sida som lägger ett live-samtal i webbläsaren: mikrofonen strömmar in i samma WebSocket via WebRTC, agentens röst strömmar tillbaka, och socketen förblir öppen hela tiden.

streamlit run app_streamlit.py