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 はこのバージョンを指しています。リリースのお知らせ には、音声セッションの料金が 1 分あたり $0.08（1 時間あたり $4.80）と記載されています。音声アシスタントやカスタマーサポート向けに、会話、割り込み処理、ツール使用を統合しています。基本的な Python、xAI API キー、websockets ライブラリがあれば、プロンプトを送り、話し声の返信を保存できます。まずは以下の例から始め、アプリの成長に合わせて録音音声、ライブマイク配信、業務ツールを追加してください。
Grok Voice 3.0 は xAI が SpaceX Super Intelligence のブランディングで開発したリアルタイム会話型音声モデルです。話し言葉またはテキスト入力を受け付け、進行中のセッション内で音声とテキストを返します。本モデルは一般的なテキスト専用の Grok モデルの代替ではなく、音声エージェント用途に最適化されています。
従来の音声アシスタントは音声認識、言語モデル、音声合成を連鎖させます。Grok Voice は代わりに、会話機能とツール対応を統合した音声対音声音声セッションを公開します。このアーキテクチャにより開発者のオーケストレーション層を簡素化できますが、アプリケーション側では依然として音声の取得、伝送、認可、業務連携、監視が必要です。
The Grok Voice 3.0 model definition では、入出力モダリティとしてテキストと音声が定義されています。本チュートリアルでは、サーバー側 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 イベントで voice、音声フォーマット、手動ターン処理を設定し、プロンプトを送る前に session.updated を待ちます。
以下のスクリプトを grok_voice_demo.py として保存してください。1 つのテキストプロンプトを送信し、base64 エンコードの音声チャンクを収集して、モノラル 24 kHz 16-bit PCM の WAV ファイルを書き出します。API エラー、完了失敗、音声を生成しなかった応答の場合は停止します。
テキストプロンプトから 1 回分の音声返信を作成し、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": "Explain Grok Voice 3.0 briefly."}]}}))
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("The response contained no audio.")
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("Saved grok_response.wav")
asyncio.run(main())
Python の音声例を実行します。
python grok_voice_demo.py
応答が成功すると、ターミナルに Saved grok_response.wav と表示されます。そのファイルをメディアプレーヤーで開き、通常速度で完全な返信が聞こえることを確認してください。ファイルが見当たらない、または再生できない場合は、より多くの機能を追加する前に、返ってきたイベントや音声設定を確認する理由になります。
リアルタイムイベントのリファレンスには、ここで使用しているセッションの確認と応答ライフサイクルが記載されています。このスクリプトは 1 ターンの完了を待ってからファイルを書き込みますが、インタラクティブな音声アプリケーションでは到着した音声チャンクから順次再生すべきです。
この例ではモノラル 24 kHz 16-bit 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("Use mono, 24 kHz, 16-bit PCM WAV audio.")
pcm = source.readframes(source.getnframes())
if len(pcm) < SAMPLE_RATE * 2 // 10:
raise ValueError("Use a spoken recording longer than 100 ms.")
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 コンテナのヘッダーではなく、WAV ファイルから取り出した生の PCM サンプルを送ります。最初のスクリプトでは手動ターン処理を明示的に選択しているため、バッファのコミットと応答のリクエストは別のアクションになります。
インタラクティブな会話では、音声を継続的に取得し、設定済みの入力フォーマットに変換して短いチャンクに分けて送信し、別の受信ループで応答を処理します。録音ファイルの例で用いた手動モードではなく、自動ターン検出には server_vad を選択してください。サーバーが既に返信の作成を進めているときに、二重に response.create を追加しないように注意します。
割り込み時は、キューに入っているアシスタント音声の再生を速やかに停止してください。ネットワーク上のキャンセルだけでは、アプリケーションがすでにバッファした音声は取り除けません。再生キューを小さく保ち、実際にリスナーがどれだけの音声を聞いたかを追跡して、会話状態の整合性を保てるようにします。
アプリケーションは注文照会、スケジューリング、本人確認などのツールを公開できます。エージェントは複雑な口頭リクエストを解釈し、認可された関数を呼び出し、結果を用いて会話を続けられます。これは顧客が 1 回の通話で関連する変更を複数求める場合に特に有用です。
API はカスタム関数とサーバー管理ツールをサポートします。カスタム関数の場合、アクション自体はアプリケーションが実装します。ツールを定義するだけではモデルが自動でデータベースに接続されるわけではありません。
まずは配達状況の確認のような読み取り専用ツールから始めましょう。予約変更、返金、注文確定のような状態を変えるアクションでは、アプリケーション側で本人確認、確認プロンプト、重複リクエスト防止を徹底してください。
クライアント側接続には短期認証情報を使用します。サーバーは恒久的な API キーで短命トークンを要求し、そのトークンをクライアントに渡します。自分のトークンエンドポイントへのリクエストを認証し、利用制限を適用して、無制限のゲートウェイにならないようにします。
マイクの同意、録音コントロール、接続状態をインターフェースで常に見えるようにしてください。接続喪失は明示的に処理し、古い再生を停止し、接続が復旧中であることをユーザーに伝え、すでに完了している可能性があるアクションを繰り返さないようにします。
音声利用とカスタム連携は別々の課金になる場合があります。本チュートリアルに関係する公表レートは、リアルタイムセッションとテキスト入力です。単体の文字起こしや音声生成は別サービスです。
料金は 2026 年 10 月 29 日時点で確認。最新の料金は公式の料金ページをご覧ください。
例えば、課金対象のセッション分数が 500 分の場合、音声の基本料金は $40 に相当します。この見積もりにはテキスト入力、任意のツール、テレフォニー、自身のインフラコストは含みません。短いテストセッションから始め、会話が終わったらアイドル状態の接続は閉じてください。
まずは Grok Voice 3.0 API の 1 完結ターンから始めましょう。接続し、セッションを設定し、プロンプトを送信して、音声を受け取り、再生します。その経路が動作したら、録音音声を追加し、次にマイク入力の取得とストリーミング再生を組み込みます。会話とエラーハンドリングの経路が堅牢になってから、業務ツールを導入してください。