Choose your path
使用 Python 連線至 Grok Voice 3.0、產生語音回覆、傳送音訊、新增工具，並疑難排解常見的即時 API 問題。
from openai import OpenAI
client = OpenAI(
api_key="YOUR_COMETAPI_KEY",
base_url="https://api.cometapi.com/v1",
)
response = client.chat.completions.create(
model="gpt-5-mini",
messages=[{"role": "user", "content": "Build this workflow."}],
)
print(response.choices[0].message.content)Grok Voice 3.0 是 xAI 的即時語音到語音模型，於 2026 年 10 月 14 日發佈。其 API 模型名稱為 grok-voice-3.0；截至 2026 年 11 月 3 日，grok-voice-latest 指向此版本。在發佈公告中，語音會話價格為每分鐘 $0.08（每小時 $4.80）。它結合了對話、打斷處理與工具使用，適用於語音助理與客服。具備基礎 Python、xAI API 金鑰與 websockets 函式庫後，你可以傳送提示並儲存語音回覆。從下方範例開始，然後隨著應用成長加入錄音檔、即時麥克風串流與商務工具。
Grok Voice 3.0 是 xAI 開發的即時對話語音模型，歸屬於 SpaceX Super Intelligence 品牌。它可在進行中的會話中接收語音或文字輸入，並回傳音訊與文字。該模型針對語音代理使用情境進行最佳化，而非作為一般純文字 Grok 模型的即插即用替代品。
傳統語音助理通常串接語音辨識、語言模型與語音合成。Grok Voice 則提供整合對話行為與工具支援的語音到語音會話。這種架構可簡化開發者的協作層，但應用仍需處理音訊擷取、傳輸、授權、商務整合與監控。
Grok Voice 3.0 模型定義指出其輸入與輸出樣式包含文字與音訊。對本教學而言，第一個有用的檢查點是從伺服器端 Python 腳本得到可播放的回覆。
官方發佈報告引用了 2026 年 10 月 13 日的 Artificial Analysis 結果：
這些是公開的基準測試結果，並不保證你的部署能達到相同表現。正式上線前，請以你實際的口音、噪音環境、工具與升級（轉接）流程進行測試。
在 xAI Console 建立或登入帳戶、產生 API 金鑰，並確認你的帳戶具備存取權與可用額度。於本機終端機或受信任的伺服器執行 Python 範例。
在 xAI Console 產生金鑰。將其儲存在環境變數中，而非硬編碼在應用程式裡。
為當前 Bash 終端機設定 API 金鑰。
export XAI_API_KEY="your_xai_api_key"
在 Windows PowerShell：
為當前 PowerShell 工作階段設定 API 金鑰。
$env:XAI_API_KEY="your_xai_api_key"
在你的 Python 環境安裝 WebSocket 用戶端。
python -m pip install "websockets>=14,<18"
在同一個終端機工作階段執行剩餘指令。若使用虛擬環境，請先啟用再安裝套件。
原生 Realtime API 使用 WebSocket 連線。不同於一般的純文字聊天補全，它會在對話進行中交換持續的會話事件並串流音訊片段。
API 接受在 WebSocket URL 中指定版本化的模型名稱。範例使用 grok-voice-3.0，以明確要求版本。以 session.update 事件設定語音、音訊格式與手動回合處理；在提交提示前先等待 session.updated。
將以下腳本另存為 grok_voice_demo.py。它提交一個文字提示、收集以 base64 編碼的音訊片段，並寫入單聲道、24 kHz、16 位元 PCM 的 WAV 檔。若出現 API 錯誤、完成狀態不成功，或回應未產生音訊，也會停止。
從文字提示產生一段語音回覆並儲存為 WAV 檔。
import asyncio, base64, json, os, wave
import websockets
SAMPLE_RATE = 24000
async def receive_event(ws):
event = json.loads(await asyncio.wait_for(ws.recv(), 60))
if event.get("type") == "error":
raise RuntimeError(event)
return event
async def main():
url = "wss://api.x.ai/v1/realtime?model=grok-voice-3.0"
headers = {"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"}
async with websockets.connect(url, additional_headers=headers) as ws:
await ws.send(json.dumps({"type": "session.update", "session": {
"voice": "eve", "turn_detection": {"type": None},
"audio": {
"input": {"format": {"type": "audio/pcm", "rate": SAMPLE_RATE}},
"output": {"format": {"type": "audio/pcm", "rate": SAMPLE_RATE},
"transport": "json"}}}}))
async with asyncio.timeout(30):
while (await receive_event(ws)).get("type") != "session.updated":
pass
await ws.send(json.dumps({"type": "conversation.item.create", "item": {
"type": "message", "role": "user",
"content": [{"type": "input_text", "text": "請簡要說明 Grok Voice 3.0。"}]}}))
await ws.send(json.dumps({"type": "response.create"}))
chunks = []
async with asyncio.timeout(120):
while True:
event = await receive_event(ws)
if event["type"] in ("response.output_audio.delta", "response.audio.delta"):
chunks.append(base64.b64decode(event["delta"]))
elif event["type"] == "response.done":
if event.get("response", {}).get("status") != "completed":
raise RuntimeError(event)
break
if not chunks:
raise RuntimeError("回應中沒有包含音訊。")
with wave.open("grok_response.wav", "wb") as wav:
wav.setparams((1, 2, SAMPLE_RATE, 0, "NONE", "not compressed"))
wav.writeframes(b"".join(chunks))
print("已儲存 grok_response.wav")
asyncio.run(main())
執行 Python 語音範例。
python grok_voice_demo.py
成功回應後，終端機會印出 Saved grok_response.wav。以媒體播放器開啟該檔案並確認能以正常速度播放完整回覆。若檔案缺失或無法播放，請在加入更多功能前先檢查返回事件與音訊設定。
即時事件參考描述了此處使用的會話應答與回應生命週期。該腳本會等待整個回合完成後才寫檔；互動式語音應用應在音訊片段抵達時立即播放。
此範例使用單聲道、24 kHz、16 位元 PCM 的 WAV 檔。Grok Voice 3.0 也支援其他 PCM 取樣率、μ-law、A-law 與 Opus。實際格式必須與 session.update 設定相符。將前述腳本中的 conversation.item.create 區塊替換為下方片段。保留後續的 response.create 呼叫與現有接收迴圈。
在 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("請使用單聲道、24 kHz、16 位元 PCM WAV 音訊。")
pcm = source.readframes(source.getnframes())
if len(pcm) < SAMPLE_RATE * 2 // 10:
raise ValueError("請使用長度超過 100 毫秒的語音錄音。")
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
將此替換片段縮排至與原始文字訊息區塊相同層級，置於 WebSocket 內容中。它傳送的是 WAV 檔中的原始 PCM 取樣資料，而非 WAV 容器標頭。第一個腳本已明確選擇手動回合處理，因此提交緩衝區與請求回應為兩個獨立動作。
對於互動式對話，持續擷取音訊、轉換為已設定的輸入格式，並以短片段送出，同時由另一個接收迴圈處理回應。選擇 server_vad 以啟用自動回合偵測，而非錄音檔範例所用的手動模式。當伺服器已在建立回覆時，避免再發出第二個 response.create。
遇到打斷時，要立即停止播放已排隊的助理音訊。僅靠網路取消無法移除你的應用已緩衝的聲音。保持播放佇列精簡，並追蹤聽眾實際聆聽的音訊量，以維持對話狀態一致。
應用可以提供工具，例如訂單查詢、排程或帳戶驗證。代理能理解複雜的口語請求、呼叫已授權的函式，並使用結果繼續對話。當客戶在一次通話中請求多個相關變更時特別有用。
API 支援自訂函式與伺服器代管工具。對於自訂函式，你的應用需自行實作動作；僅定義工具並不會自動把模型連上你的資料庫。
先從唯讀工具開始，例如查詢訂單配送狀態。對於會變更預訂、執行退款或下訂的動作，請在應用中強制執行身分驗證、確認與重複請求防護。
對客戶端連線使用臨時憑證。你的伺服器以永久 API 金鑰請求短期權杖，並將該權杖提供給客戶端。對你的權杖端點進行驗證並施加使用限制，避免成為無限制的閘道。
在介面中讓麥克風同意、錄音控制與連線狀態清楚可見。明確處理連線中斷：停止陳舊的播放、告知使用者連線正在恢復，並避免重播可能已完成的動作。
語音使用與自訂整合可能產生各自的費用。對本教學而言，相關的公開費率為即時會話與文字輸入；獨立的轉錄與語音產生屬於其他服務。
費率於 2026 年 10 月 29 日查核。請參閱官方定價頁面以取得最新價格。
例如，500 分鐘的可計費會話對應於 $40 的基礎語音費用。此估算不含文字輸入、選用工具、電話整合與你的基礎設施成本。從短測試會話開始，並在對話結束時關閉閒置連線。
先完成 Grok Voice 3.0 API 的一個完整回合：連線、設定會話、提交提示、接收音訊並播放結果。當這條路徑運作穩定後，再加入錄製語音，接著為其建立麥克風擷取與串流播放。僅在對話與錯誤處理流程可靠後，才引入商務工具。