Tutorial API Grok Voice Think Fast 2.0: Bangun Agen Suara Real-Time di Python

Grok Voice Think Fast 2.0 dari SpaceXAI adalah model speech-to-speech. Anda mengirim audio melalui WebSocket dan ia mengirim audio kembali; di tengahnya model dapat bernalar dan terus berbicara sementara pemanggilan fungsi yang dipilihnya sudah berjalan. Tanpa langkah terpisah speech-to-text, tanpa langkah terpisah text-to-speech.

SpaceXAI mengumumkan Think Fast 2.0 pada 29 Juli 2026: audio pertama lebih cepat, perilaku full-duplex lebih stabil (mendengarkan sambil berbicara alih-alih bergiliran ketat), dan pemanggilan tool yang menyala lebih awal dalam satu giliran. Saya akan singkat soal tolok ukur, karena yang penting untuk tutorial adalah apa yang berubah di kode Anda.

Kita akan membangun agen suara dukungan pelanggan untuk toko online. Penelepon bisa menanyakan pesanan, mengubah instruksi pengantaran, membatalkan, menyela agen di tengah kalimat, dan melanjutkan percakapan setelah koneksi terputus. Ini jalur API, bukan Voice Agent Builder tanpa kode yang dijelaskan dalam tutorial Grok Voice Agent Builder kami. Mulailah dari sana untuk versi berbasis konsol.

Apa Itu Grok Voice Think Fast 2.0?

Grok Voice Think Fast 2.0 adalah model terbaru SpaceXAI untuk Speech to Speech API, nama produk di balik apa yang kebanyakan orang sebut Grok Voice. Jika Anda masih menganggap perusahaannya sebagai xAI, itu sama: digabungkan ke SpaceX dan diberi merek ulang menjadi SpaceXAI pada 6 Juli 2026. API tidak ikut berganti merek, jadi setiap pengenal di bawah ini masih bertuliskan xai, dari variabel XAI_API_KEY hingga host api.x.ai.

Tumpukan suara tradisional merangkai tiga layanan: speech-to-text, model bahasa, lalu text-to-speech, dan setiap lompatan menambah latensi serta tempat konteks bisa hilang. Think Fast 2.0 mereduksi itu menjadi satu model yang menerima audio atau teks dan menghasilkan audio atau teks melalui koneksi yang sama.

WebSocket speech-to-speech versus arsitektur pipeline tiga layanan. Gambar oleh Penulis.

Untuk agen yang bertindak, bukan hanya berbicara, yang penting adalah penalaran dan suara berjalan paralel. SpaceXAI mengatakan pemanggilan tool "biasanya" mulai dieksekusi sebelum agen menyelesaikan kalimat pertamanya, dan kata itu membawa bobot nyata.

Pada tolok ukur yang dikutip SpaceXAI dari Artificial Analysis, Think Fast 2.0 meraih 82,9% pada Speech to Speech Index dibandingkan 75,7% untuk 1.0, dan memangkas waktu ke audio pertama dari 1,25 detik menjadi 0,70 detik. Angka vendor pada tolok ukur umum adalah hipotesis tentang alur penelepon Anda, bukan rencana uji.

Ada tiga string model yang akan Anda lihat: grok-voice-latest, grok-voice-think-fast-2.0, dan grok-voice-think-fast-1.0. Alias berguna saat prototyping dan tidak cukup stabil untuk hal lain.

Saat saya uji pada 4 Agustus 2026, grok-voice-latest masih merujuk ke grok-voice-think-fast-1.0, dengan catatan rilis SpaceXAI menjadwalkan perpindahan ke Think Fast 2.0 untuk hari berikutnya. Pergantian itu sama besarnya perubahan harga seperti perubahan model, $0,08 per menit audio dibandingkan $0,05 untuk 1.0, sehingga alias yang tidak dipin akan lebih mahal tanpa ada perubahan satu baris kode Anda. Sematkan string versi pada apa pun yang Anda deploy.

Apa yang Akan Kita Bangun

Agen ini mencakup hal-hal yang ditanyakan ke jalur dukungan: mencari pesanan, menemukan dari email saat penelepon tak punya nomor, mengubah instruksi pengantaran, membatalkan, membuka atau memeriksa tiket, dan menyerahkan panggilan ke manusia. Interupsi dan koneksi yang terputus akan muncul sepanjang jalan.

Ini terdiri dari beberapa file kecil, bukan satu skrip, karena setiap bagian memiliki tugas berbeda dan Anda akan ingin mengujinya secara terpisah. Berikut strukturnya:

• config.py memuat kunci API dan menyimpan string model, sample rate, dan URL endpoint

• voice_client.py membungkus WebSocket, melacak penagihan, dan mengekspos helper kirim/terima

• tools.py mendefinisikan fungsi pesanan dan penyimpanan pesanan kecil dalam memori sebagai pengganti basis data nyata

• assistant.py menyimpan prompt sistem, konfigurasi sesi, dan event loop yang menyatukan semuanya

• token_server.py adalah endpoint FastAPI kecil yang mencetak token sementara

• app_streamlit.py menempatkan klien yang sama di balik panggilan browser langsung, yang akan saya bahas kembali setelah bagian pengujian

Jalur pembelajaran berjalan dari terminal. Demo menambahkan mikrofon.

Prasyarat

Anda memerlukan akun SpaceXAI dengan kunci API, pengaturan penagihan yang didanai (tidak ada tingkat gratis permanen, dan kredit promosi akun baru tidak akan mencukupi), serta cukup nyaman dengan asyncio dan WebSocket untuk mengikuti tanpa penjelasan baris-demi-baris tentang await.

Contoh quick-start SpaceXAI menggunakan paket websockets mentah alih-alih SDK khusus, dan kita juga demikian. Dokumennya tidak menyebutkan versi Python yang diperlukan. Saya menguji pada 3.11.

Simpan kunci API di server. Jika aplikasi browser atau seluler berbicara langsung ke Voice API, ia mendapatkan token sementara alih-alih kunci asli Anda, dibahas di bagian keamanan di bawah.

Menyiapkan proyek

Setiap file di bawah ada di repo proyek, jadi Anda bisa mengklonnya alih-alih menyalin potongan kode:

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 menangani koneksi realtime dan python-dotenv membaca kunci Anda. Sisanya mencakup endpoint token dan demo browser. Letakkan kunci Anda di .env:

XAI_API_KEY=xai-your-key-here

Itu sebagian besar penyiapannya. Koneksinya bagian yang menarik.

Memahami Grok Voice Realtime API

Grok Voice adalah nama produk. Yang sebenarnya Anda tulis kodenya adalah endpoint WebSocket di wss://api.x.ai/v1/realtime, dan seluruh percakapan berlangsung sebagai aliran event JSON melalui satu socket itu.

Siklus hidup event

Sebuah koneksi mengikuti bentuk tetap: server mengirim session.created dan conversation.created segera setelah Anda terhubung, Anda mengirim session.update untuk mengonfigurasi suara dan tool, server mengonfirmasi dengan session.updated, dan dari sana Anda membuat item percakapan dan meminta respons. Saya menjalankan ini dengan kunci live dan urutannya cocok dengan dokumen persis.

• session.update (klien) mengonfigurasi suara, instruksi, tool, dan format audio

• conversation.item.create (klien) menambahkan pesan pengguna, pesan asisten, atau hasil tool

• response.create (klien) meminta model untuk berbicara; server VAD mengirim ini untuk Anda secara otomatis

• response.output_audio.delta dan response.output_audio_transcript.delta (server) mengalirkan balasan saat dihasilkan

• response.done (server) menutup satu giliran

Dua hal yang sering menjebak orang. Halaman dokumentasi Speech to Speech yang saya tautkan di atas menyebut event conversation.item.created saat melanjutkan sesi, tetapi referensi event kanonik hanya mencantumkan conversation.item.added, dan itulah yang tiba di setiap uji yang saya jalankan, jadi kodenya mengacu ke itu. Anda juga akan melihat event ping yang tidak didokumentasikan beberapa detik setelah kebanyakan koneksi, disebutkan agar Anda tidak membacanya sebagai error.

Format audio dan transport

Codec dan transport adalah pilihan terpisah. Codec, diatur di audio.input.format dan audio.output.format, adalah audio/pcm (Linear16, default 24000 Hz), audio/pcmu atau audio/pcma (G.711 pada 8 kHz, untuk teleponi), atau audio/opus (24 kHz). Transport adalah bagaimana byte itu berjalan di kabel:

• json (default) mengirim audio sebagai teks base64 di dalam input_audio_buffer.append dan response.output_audio.delta, mudah untuk logging dan debug

• binary mengirim byte codec mentah sebagai frame biner WebSocket, melewati overhead base64 dengan biaya loop penerima yang harus bercabang pada tipe pesan

Mulailah dengan JSON. Setiap contoh dalam dokumen menggunakannya, sangat mudah diperiksa, dan overhead base64 bukanlah penghambat pada build agen dukungan. Beralih ke biner jika Anda mengukur ada alasannya.

Kompatibilitas dengan OpenAI Realtime API

Lewati jika Anda tidak pernah menyentuh OpenAI Realtime API. Bagi yang lain, Speech to Speech API mengikuti OpenAI Realtime API cukup dekat sehingga sebagian besar kode klien dapat dipindahkan hanya dengan mengganti base URL dan kunci, tetapi ini bukan drop-in sempurna.

Transkrip tiba sebagai conversation.item.input_audio_transcription.updated di sini alih-alih delta milik OpenAI, beberapa event OpenAI tidak didukung, dan SpaceXAI menambahkan ekstensi sendiri: force_message untuk baris pengungkapan terskrip, resumption untuk penyambungan kembali, dan replace untuk memperbaiki pelafalan merek sebelum text-to-speech.

Membangun Agen Suara Real-Time

Cukup protokolnya. Berikut klien yang berbicara dengannya.

Menyambung dan mengonfigurasi sesi

Koneksi dibuka dengan bearer token dan parameter kueri model, dan pesan pertama yang Anda kirim mengonfigurasi semua perilaku agen:

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 adalah prompt sistem, dan model ini menginginkan yang pendek. Catatan migrasi SpaceXAI menyarankan menyederhanakan prompt yang ditulis untuk model suara era GPT yang lebih lama, bukan memindahkannya mentah-mentah. Prompt saya menyuruh agen menjaga jawaban singkat, bertanya satu per satu, dan membacakan ulang setiap penulisan sebelum bertindak. Konfirmasi lisan adalah peningkatan UX, bukan kontrol keamanan. Aplikasi Anda tetap menegakkan otorisasi pada proses penulisan itu sendiri.

Satu hal yang mengejutkan saya: string model yang tidak dikenal tidak menimbulkan error saat koneksi, melainkan diam-diam kembali ke grok-voice-think-fast-1.0. Menurunkan permintaan berbayar karena salah ketik, tanpa memberi tahu, adalah default yang aneh. Catat kolom session.model dari session.created sekali saat startup dan periksa apakah Anda mendapatkan yang diminta.

Output terminal menampilkan session.created setelah terhubung. Gambar oleh Penulis.

Mengalirkan audio pengguna

Dengan turn_detection.type disetel ke server_vad, Anda hanya perlu terus menambahkan audio. Server memutuskan kapan penelepon berhenti berbicara dan memicu respons untuk Anda. Setel ke null sebagai gantinya dan Anda yang menentukan sendiri, mengkomit buffer secara eksplisit saat Anda anggap gilirannya selesai.

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 memiliki tiga kenop, dan menyetelnya salah adalah cara paling umum saya melihat agen suara terasa rusak sementara tidak ada error di log. Tidak satu pun muncul dalam echo session.updated secara default, jadi periksa terhadap dokumen, jangan berasumsi.

• threshold (0,1 hingga 0,9, default 0,85), seberapa keras audio agar dihitung sebagai ucapan; naikkan di ruangan bising, turunkan jika pembicara pelan terlewat

• silence_duration_ms, berapa lama penelepon diam sebelum server mengakhiri gilirannya; terlalu pendek memotong orang di tengah pikiran, terlalu panjang terasa lamban

• prefix_padding_ms (default 333), sepotong audio yang disimpan tepat sebelum ucapan terdeteksi, agar suku kata pertama tidak terpotong

Setel silence_duration_ms lebih dahulu jika penelepon terus terpotong saat berhenti sejenak untuk berpikir. Ini yang saya sentuh sebelum dua lainnya.

Menerima dan memutar respons

Audio tiba dalam potongan kecil sebagai response.output_audio.delta, dan inti dari streaming adalah Anda memutar setiap potongan saat mendarat alih-alih menunggu 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)

Simpan transkrip meski di produksi. Itu alat debug termurah saat penelepon berkata agen "mengucapkan sesuatu yang aneh."

Menambahkan Tool ke Agen Suara

Agen suara yang hanya berbicara adalah chatbot dengan mikrofon.

Membuat tool pesanan

Setiap tool adalah skema JSON plus fungsi Python biasa di sisi kita. Model tidak pernah menyentuh basis data, hanya melihat apa yang dikembalikan fungsi kita.

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
]

Operasi baca seperti check_order_status aman diulang jika terjadi timeout. Operasi tulis tidak: mengulang update_delivery_instructions setelah timeout ambigu bisa menerapkan perubahan yang sama dua kali. Baris konfirmasi dalam prompt tidak mencegah itu, jadi berikan tulis sebuah idempotency key atau pemeriksaan duplikat.

Letakkan penolakan di fungsi juga. cancel_order mengembalikan alasan dan alternatif alih-alih membatalkan pesanan yang sudah dikirim, karena prompt yang mengatakan "jangan pernah batalkan pesanan yang sudah dikirim" hanyalah saran, sedangkan fungsi yang menolak itu tidak.

Menangani loop pemanggilan tool

Empat langkah, dan urutannya lebih penting dari kelihatannya. Model mengirim response.function_call_arguments.done, kode Anda menjalankan fungsi, Anda mengirim hasilnya kembali sebagai item function_call_output , dan barulah Anda meminta model untuk melanjutkan.

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),
        },
    }))

Jika model butuh lebih dari satu tool untuk satu permintaan, ia memicu beberapa event function_call_arguments.done sebelum audio diputar. Selesaikan semuanya dan kirim setiap hasil sebelum satu response.create pun. Mengirimnya terlalu cepat membuat model menjawab tanpa konteks dari pemanggilan yang masih berjalan.

Ada jebakan yang didokumentasikan SpaceXAI dan tetap saya alami pada percobaan pertama: mengirim response.create tepat saat hasil tool Anda dikirim bisa tumpang tindih dengan kalimat pembuka yang masih diputar agen. Dalam satu run, ia membuka dengan "Saya akan segera mengecek status pesanan ORD-1042" dan memanggil tool di tengah kalimat, jadi respons instan akan menimpa kalimat pembukanya sendiri.

Tunggu audio giliran saat ini selesai, dan tampilkan status "sedang berpikir" singkat di antaranya.

Alur pemanggilan tool sebelum melanjutkan respons. Gambar oleh Penulis.

Mengelola Interupsi dan Status Percakapan

Dua masalah terpisah di sini. Penelepon berbicara menimpali agen di tengah respons, dan WebSocket terputus lalu perlu dilanjutkan kembali.

Mendukung interupsi alami

Dengan server_vad aktif, barge-in otomatis terjadi di sisi server: begitu mendeteksi penelepon berbicara lagi, ia memberi sinyal input_audio_buffer.speech_started dan menghentikan generasi respons lama. Tugas Anda adalah separuh jabat tangan di klien, mengosongkan audio yang sudah antre agar agen diam, bukan menyelesaikan kalimat yang tak diminta didengar.

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

Untuk sesi manual non-VAD, response.cancel melakukan tugas yang sama sesuai permintaan. Ada juga conversation.item.truncate untuk memangkas item asisten ke apa yang benar-benar terdengar. Dokumen mengonfirmasi keberadaannya tetapi tidak menjelaskan kapan menembakkannya saat barge-in berlangsung, jadi uji sendiri waktunya.

Saya menguji ini dengan perubahan instruksi pengantaran di tengah respons: mulai permintaan, menyela dengan alamat berbeda saat agen sedang mengonfirmasi. Yang penting adalah apakah agen menerapkan instruksi yang dikoreksi alih-alih diam-diam menyelesaikan yang lama, bukan apakah audio berhenti. Pastikan terhadap catatan pesanan, bukan keheningan. Demo browser di akhir memungkinkan Anda mendengarnya.

Melanjutkan sesi yang terputus

Melanjutkan sesi bersifat opt-in dan itu bukan memori. Setel resumption.enabled: true pada session.update, ambil ID dari event conversation.created, dan jika socket terputus, sambungkan kembali dengan ?conversation_id=<id> pada URL dan ikutkan lagi pada koneksi baru.

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

Giliran yang tersimpan, transkrip, pemanggilan tool, dan hasil tool akan diputar ulang sebelum pertanyaan Anda berikutnya, dan cache menghilang setelah 30 menit tidak aktif. Saya mengujinya dengan menanyakan pesanan, memutus koneksi, dan menyambung kembali untuk tindak lanjut tanpa mengulang; agen mengambil ETA lagi dengan benar.

Satu catatan yang tidak didokumentasikan: pemutaran ulang tidak mendarat seketika, jadi pertanyaan yang ditembak tepat saat socket terbuka bisa mendahuluinya dan kembali tanpa memori giliran sebelumnya. Beri jeda sejenak sebelum Anda menyalahkan resumption.

Log terminal dari sesi yang dilanjutkan. Gambar oleh Penulis.

Jangan gunakan ini sebagai pengganti menyimpan status pesanan ke basis data Anda sendiri. Jika cache kedaluwarsa atau penelepon menelepon kembali besok, Anda mulai dari nol konteks, dan itu memang dirancang demikian.

Mengamankan dan Memantau Agen

Jangan pernah menaruh kunci API permanen di kode browser atau seluler. Jika klien terhubung langsung alih-alih melalui server Anda, cetak token berumur pendek:

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": ...}

Browser tidak bisa menyetel header Authorization kustom pada jabat tangan WebSocket, jadi ia meneruskan token melalui header sec-websocket-protocol, diawali dengan xai-client-secret..

Server mencetak token, browser bergabung dalam panggilan. Gambar oleh Penulis.

Penagihan berjalan pada dua meteran. Audio, dikirim atau diterima, dikenai tarif $0,08 per menit seperti yang saya sebutkan sebelumnya, yaitu $4,80 per jam, dan setiap conversation.item.create yang bukan audio dan bukan function_call_output dikenai biaya tetap $0,004. response.create tidak ditagih sama sekali. Setiap response.done membawa objek usage, yang dalam uji saya melaporkan output_audio_seconds bersama billable_audio_seconds terpisah. Tagih dari itu, bukan dari perkiraan.

Batas terdokumentasi pada Speech to Speech API adalah 10 sesi bersamaan per tim dan batas sesi 120 menit, keduanya di us-east-1. Jangan merencanakan kapasitas dari angka Voice Agent API, yang berbeda.

Soal privasi, jadilah presisi. FAQ keamanan SpaceXAI menyebut permintaan dan respons API disimpan terenkripsi selama 30 hari untuk pemantauan penyalahgunaan dan tidak digunakan untuk pelatihan tanpa izin, serta tim dapat menyalakan Zero Data Retention, meski ZDR menonaktifkan riwayat percakapan agen suara yang dipersisten dan karenanya tidak berfungsi dengan resumption.

Jika Anda mengungkapkan bahwa panggilan direkam atau ditangani AI, itulah yang dilakukan ekstensi force_message yang saya sebut tadi. Barisnya diputar persis seperti yang ditulis alih-alih apa pun yang diparafrasekan model.

Menguji Agen Suara

Status 200 pada jabat tangan WebSocket tidak memberi tahu apakah agen melakukan hal yang benar. Ujilah hasilnya, bukan hanya koneksinya.

• Pencarian pesanan yang bersih, memeriksa jawaban lisan terhadap catatan, bukan hanya bahwa respons tiba
• Respons yang disela, mengonfirmasi pemutaran berhenti dan agen menangani permintaan baru
• Pembaruan pengantaran yang butuh konfirmasi, diperiksa terhadap catatan pesanan
• Penolakan, seperti membatalkan pesanan yang sudah dikirim, di mana agen harus menjelaskan aturan alih-alih meminta maaf
• Nomor pesanan yang tidak dikenal, memastikan agen mengatakan demikian alih-alih mengarang status
• Tool yang mengembalikan error, memeriksa agen mengucapkannya alih-alih macet
• Penyambungan ulang dan resumption, termasuk jedela pemutaran ulang yang saya alami tadi
• Audio berisik, ucapan cepat, dan penelepon yang mengeja angka dan alamat

Saya menjalankan sebagian besar ini dengan kunci live saat menulis. Kegagalan menariknya bersifat perilaku, bukan error: timing resumption di atas, dan threshold VAD di luar rentang yang diterima alih-alih ditolak, hal-hal yang akan terkirim dalam keadaan diam-diam rusak jika Anda hanya menguji jalur bahagia. Tambahkan uji multibahasa juga, dan lihat FAQ untuk seluk-beluk cara memberi nama bahasa.

Dua di antaranya tidak bisa diuji dengan mengetik. app_streamlit.py adalah halaman Streamlit yang menempatkan panggilan live di browser: mikrofon mengalir ke WebSocket yang sama melalui WebRTC, suara agen mengalir kembali, dan socket tetap terbuka sepanjang waktu.

streamlit run app_streamlit.py