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 mengirimkan audio kembali; di antaranya, model dapat bernalar dan terus berbicara sementara panggilan fungsi yang dipilihnya sudah berjalan. Tidak ada langkah terpisah untuk speech-to-text, tidak ada langkah terpisah untuk 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 mengeksekusi 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 dapat menanyakan pesanan, mengubah instruksi pengiriman, membatalkan, menyela agen di tengah kalimat, dan melanjutkan percakapan setelah koneksi terputus. Ini jalur API, bukan Voice Agent Builder tanpa kode yang dijelaskan oleh 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, sama saja: perusahaan tersebut dilebur ke SpaceX dan berganti nama menjadi SpaceXAI pada 6 Juli 2026. API tidak ikut rebranding, jadi setiap pengenal di bawah tetap 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 titik di mana konteks bisa hilang. Think Fast 2.0 merangkum semuanya 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 alih-alih hanya berbicara, yang penting adalah penalaran dan ucapan berjalan paralel. SpaceXAI mengatakan pemanggilan tool "biasanya" mulai dieksekusi sebelum agen menyelesaikan kalimat pertamanya, dan kata itu memang berarti.

Pada tolok ukur yang dikutip SpaceXAI dari Artificial Analysis, Think Fast 2.0 meraih 82,9% pada Speech to Speech Index dibanding 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 pengujian.

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 yang lain.

Saat saya uji pada 4 Agustus 2026, grok-voice-latest masih mengarah ke grok-voice-think-fast-1.0, dengan catatan rilis SpaceXAI menjadwalkan perpindahan ke Think Fast 2.0 untuk hari berikutnya. Pergantian itu adalah perubahan harga sekaligus perubahan model, $0,08 per menit audio dibanding $0,05 untuk 1.0, jadi alias yang tidak dipatok versi menjadi lebih mahal tanpa satu baris kode Anda berubah. Patok string versi pada apa pun yang Anda deploy.

Apa yang Akan Kita Bangun

Agen mencakup pertanyaan umum pada jalur dukungan: melihat pesanan, mencari dari email saat penelepon tidak punya nomor, mengubah instruksi pengiriman, membatalkan, membuka atau memeriksa tiket, dan mengalihkan panggilan ke manusia. Interupsi dan koneksi terputus akan muncul di sepanjang jalan.

Ini terdiri dari beberapa berkas kecil, bukan satu skrip, karena tiap bagian punya tugas berbeda dan Anda akan ingin mengujinya terpisah. Inilah strukturnya:

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

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

• tools.py mendefinisikan fungsi pesanan dan penyimpanan pesanan kecil di memori sebagai pengganti database nyata

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

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

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

Alur pembelajaran berjalan dari terminal. Demo menambahkan mikrofon.

Prasyarat

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

Contoh quick-start SpaceXAI menggunakan paket websockets mentah alih-alih SDK khusus, dan kita juga begitu. Dokumentasi tidak menyatakan versi Python yang dibutuhkan. Saya menguji pada 3.11.

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

Menyiapkan proyek

Setiap berkas 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.txtDidukung oleh

websockets membawa koneksi realtime dan python-dotenv membaca kunci Anda. Sisanya untuk endpoint token dan demo browser. Letakkan kunci Anda di .env:

XAI_API_KEY=xai-your-key-hereDidukung oleh

Itu sebagian besar penyiapannya. Koneksi adalah bagian yang menarik.

Memahami Grok Voice Realtime API

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

Siklus hidup event

Koneksi mengikuti pola tetap: server mengirim session.created dan conversation.created segera setelah Anda terhubung, Anda mengirim session.update untuk mengonfigurasi voice dan tool, server mengonfirmasi dengan session.updated, dan dari sana Anda membuat item percakapan dan meminta respons. Saya menjalankan ini dengan kunci langsung dan urutannya persis seperti di dokumen.

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

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

• response.create (klien) meminta model untuk berbicara; VAD server 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 giliran

Ada dua hal yang sering menjebak orang. Halaman dokumentasi Speech to Speech yang saya tautkan di atas menyebut event conversation.item.created selama melanjutkan sesi, tetapi referensi event kanonik hanya mencantumkan conversation.item.added, dan itulah yang tiba di setiap pengujian yang saya jalankan, jadi kodinglah berdasarkan itu. Anda juga akan melihat event ping tak terdokumentasi beberapa detik setelah kebanyakan koneksi, disebutkan agar Anda tidak membacanya sebagai error.

Format audio dan transport

Codec dan transport adalah pilihan terpisah. Codec, disetel di audio.input.format dan audio.output.format, adalah audio/pcm (Linear16, bawaan 24000 Hz), audio/pcmu atau audio/pcma (G.711 pada 8 kHz, untuk telepon), atau audio/opus (24 kHz). Transport adalah cara byte tersebut dikirim di wire:

• json (bawaan) 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 jenis pesan

Mulai dengan JSON. Setiap contoh di dokumen menggunakannya, mudah diinspeksi, dan overhead base64 bukanlah penghambat untuk build agen dukungan. Pindah ke biner jika Anda mengukur alasan yang kuat.

Kompatibilitas dengan OpenAI Realtime API

Lewati jika Anda belum 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 dengan mengganti base URL dan kunci, tetapi bukan pengganti 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 yang terprogram, resumption untuk sambungan ulang, dan replace untuk memperbaiki pengucapan nama merek sebelum text-to-speech.

Membangun Agen Suara Real-Time

Cukup soal protokol. Berikut klien yang berbicara dengannya.

Menyambungkan 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 wsDidukung oleh

instructions adalah prompt sistem, dan model ini menginginkan yang singkat. Catatan migrasi SpaceXAI menyarankan untuk menyederhanakan prompt yang ditulis untuk model suara era GPT ketimbang memindahkannya mentah-mentah. Prompt saya menyuruh agen menjaga jawaban tetap singkat, bertanya satu per satu, dan membacakan apa pun yang akan ditulis sebelum bertindak. Konfirmasi lisan adalah nicety UX, bukan kontrol keamanan. Aplikasi Anda tetap menegakkan otorisasi pada aksi tulisnya.

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

Keluaran terminal menampilkan session.created setelah tersambung. Gambar oleh Penulis.

Melakukan streaming 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 dan Anda yang memutuskan sendiri, mengkomit buffer secara eksplisit saat Anda yakin 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(),
    }))Didukung oleh

Server VAD punya 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 pada echo session.updated secara bawaan, jadi periksa terhadap dokumen alih-alih berasumsi.

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

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

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

Setel silence_duration_ms lebih dulu jika penelepon sering terpotong saat jeda berpikir. Itu yang saya ubah sebelum menyentuh dua kenop lainnya.

Menerima dan memutar respons

Audio tiba dalam potongan kecil sebagai response.output_audio.delta, dan poin dari streaming adalah Anda memutar setiap potongan begitu 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)Didukung oleh

Simpan transkrip bahkan di produksi. Ini 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 database, ia 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
]Didukung oleh

Operasi baca seperti check_order_status aman diulangi jika terjadi timeout. Operasi tulis tidak: mengulangi update_delivery_instructions setelah timeout ambigu dapat menerapkan perubahan yang sama dua kali. Baris konfirmasi di prompt tidak menghentikannya, jadi beri tulis kunci idempoten atau pemeriksaan duplikasi.

Letakkan juga penolakan di fungsi. cancel_order mengembalikan alasan dan alternatif alih-alih membatalkan pesanan yang sudah dikirim, karena prompt yang mengatakan "jangan pernah membatalkan pesanan yang sudah dikirim" adalah saran sementara fungsi yang menolak adalah aturan.

Menangani loop pemanggilan tool

Empat langkah, dan urutannya lebih penting dari yang terlihat. Model mengirim response.function_call_arguments.done, kode Anda menjalankan fungsi, Anda mengirim hasil 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),
        },
    }))Didukung oleh

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

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

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

Alur panggilan tool sebelum melanjutkan respons. Gambar oleh Penulis.

Mengelola Interupsi dan Status Percakapan

Ada dua masalah terpisah. Penelepon berbicara di atas agen di tengah respons, dan WebSocket terputus dan perlu dilanjutkan kembali.

Mendukung interupsi yang natural

Dengan server_vad aktif, barge-in otomatis 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 alih-alih menyelesaikan kalimat yang tak lagi diminta.

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

Untuk sesi manual tanpa VAD, response.cancel melakukan hal yang sama atas permintaan. Ada juga conversation.item.truncate untuk memangkas item asisten ke apa yang benar-benar terdengar. Dokumen mengonfirmasi fitur ini ada namun tidak kapan harus menembakkannya selama barge-in langsung, jadi uji waktunya sendiri.

Saya menguji ini dengan perubahan instruksi pengiriman di tengah respons: mulai permintaan, sela dengan alamat berbeda saat konfirmasi agen masih berjalan. 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 mendengar ini.

Melanjutkan sesi yang terputus

Melanjutkan sesi bersifat opt-in dan ini bukan memori. Setel resumption.enabled: true pada session.update, ambil ID dari event conversation.created, dan jika soket terputus, sambungkan ulang dengan ?conversation_id=<id> di URL dan lakukan opt-in 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 wsDidukung oleh

Giliran yang di-cache, transkrip, pemanggilan tool, dan hasil tool akan diputar ulang sebelum pertanyaan Anda berikutnya, dan cache hilang setelah 30 menit tanpa aktivitas. Saya mengujinya dengan menanyakan pesanan, memutus koneksi, lalu menyambung lagi untuk pertanyaan lanjutan tanpa mengulang; agen melanjutkan ETA dengan benar.

Satu hal tak terdokumentasi: pemutaran ulang tidak mendarat seketika, jadi pertanyaan yang dikirim tepat saat soket terbuka bisa mendahuluinya dan kembali tanpa ingatan tentang giliran sebelumnya. Beri jeda sedetik sebelum Anda menyalahkan resumption.

Log terminal dari sesi yang dilanjutkan. Gambar oleh Penulis.

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

Mengamankan dan Memantau Agen

Jangan pernah menempatkan kunci API permanen di kode browser atau mobile. 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": ...}Didukung oleh

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

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

Penagihan berjalan pada dua meter. Audio, yang dikirim atau diterima, berjalan pada $0,08 per menit seperti yang disebutkan 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, bersikaplah presisi. FAQ keamanan SpaceXAI mengatakan permintaan dan respons API disimpan terenkripsi selama 30 hari untuk pemantauan penyalahgunaan dan tidak digunakan untuk pelatihan tanpa izin, serta tim dapat mengaktifkan Zero Data Retention, meskipun ZDR menghapus riwayat percakapan agen suara yang dipersisten dan karenanya tidak bekerja dengan resumption.

Jika Anda mengungkapkan bahwa panggilan direkam atau ditangani AI, di situlah ekstensi force_message yang saya sebutkan sebelumnya berperan. Baris tersebut diputar persis seperti yang ditulis alih-alih apa pun yang diparafrasekan model.

Menguji Agen Suara

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

• Pencarian pesanan yang bersih, memeriksa jawaban lisan melawan catatan, bukan hanya bahwa respons tiba
• Respons yang disela, memastikan pemutaran berhenti dan agen menanggapi permintaan baru
• Pembaruan pengiriman yang memerlukan konfirmasi, diperiksa terhadap catatan pesanan
• Penolakan, seperti membatalkan pesanan terkirim, di mana agen harus menjelaskan aturan alih-alih meminta maaf
• Nomor pesanan tidak dikenal, memastikan agen mengatakannya alih-alih mengarang status
• Tool yang mengembalikan error, memastikan agen mengatakannya alih-alih macet
• Penyambungan ulang dan resumption, termasuk jeda pemutaran ulang yang saya alami tadi
• Audio bising, ucapan cepat, dan penelepon yang mengeja nomor serta alamat

Sebagian besar saya jalankan dengan kunci langsung saat menulis ini. Kegagalan menarik bersifat perilaku, bukan error: waktu resumption di atas, dan ambang VAD di luar rentang yang diterima alih-alih ditolak—jenis hal yang dikirim dalam keadaan diam-diam rusak jika Anda hanya menguji skenario bahagia. Tambahkan juga uji multibahasa, dan lihat FAQ untuk seluk-beluk cara menamai bahasa.

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

streamlit run app_streamlit.pyDidukung oleh