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 points to this version입니다. 출시 발표에 따르면 음성 세션 요금은 분당 $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 콘솔에서 계정을 생성하거나 로그인하고, API 키를 발급받아 계정 접근 권한과 사용 가능 크레딧을 확인하세요. Python 예제는 로컬 터미널 또는 신뢰할 수 있는 서버에서 실행합니다.
xAI 콘솔에서 키를 발급받으세요. 애플리케이션에 하드코딩하지 말고 환경 변수로 저장하세요.
현재 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로 저장하세요. 이 스크립트는 텍스트 프롬프트 1개를 제출하고 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": "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가 출력됩니다. 그 파일을 미디어 플레이어로 열어 정상 속도의 완전한 응답이 들리는지 확인하세요. 파일이 없거나 재생할 수 없다면, 더 많은 기능을 추가하기 전에 반환된 이벤트와 오디오 구성을 점검할 필요가 있습니다.
실시간 이벤트 레퍼런스는 여기서 사용한 세션 승인 및 응답 라이프사이클을 설명합니다. 이 스크립트는 전체 턴을 기다린 뒤 파일을 기록하지만, 대화형 음성 애플리케이션은 도착하는 대로 오디오 청크를 재생해야 합니다.
이 예제는 모노, 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("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 컨테이너 헤더가 아닌 원시 PCM 샘플을 보냅니다. 첫 번째 스크립트는 수동 턴 처리를 명시적으로 선택하므로, 버퍼 커밋과 응답 요청은 별도 동작입니다.
대화형 상호작용을 위해 오디오를 지속적으로 캡처하고, 구성된 입력 포맷으로 변환하여 짧은 청크로 전송하세요. 녹음 파일 예제의 수동 모드 대신 자동 턴 감지를 위해 server_vad를 선택합니다. 서버가 이미 응답을 생성 중일 때는 두 번째 response.create를 추가하지 마세요.
중단이 발생하면 큐에 있던 어시스턴트 오디오 재생을 신속히 중단하세요. 네트워크 취소만으로는 애플리케이션에 이미 버퍼링된 사운드를 제거하지 못합니다. 재생 큐를 작게 유지하고, 청자가 실제로 들은 오디오 양을 추적하여 애플리케이션이 대화 상태를 일관되게 유지하도록 하세요.
애플리케이션은 주문 조회, 일정 관리, 계정 확인 같은 도구를 노출할 수 있습니다. 에이전트는 복잡한 음성 요청을 해석하고, 승인된 함수를 호출한 뒤 그 결과를 사용해 대화를 이어갈 수 있습니다. 이는 고객이 한 통화에서 여러 관련 변경을 요청할 때 특히 유용합니다.
API는 커스텀 함수와 서버 관리형 도구를 지원합니다. 커스텀 함수의 경우, 도구를 정의해도 모델이 데이터베이스에 자동 연결되는 것은 아니며 애플리케이션이 동작을 구현해야 합니다.
읽기 전용 도구(예: 주문 배송 상태 확인)부터 시작하세요. 예약 변경, 환불, 주문 접수처럼 상태를 변경하는 작업에서는 애플리케이션에서 신원 확인, 확인 절차, 중복 요청 방지 등을 반드시 시행하세요.
클라이언트 측 연결에는 임시 자격 증명을 사용하세요. 서버는 영구 API 키로 단기 토큰을 요청하고, 그 토큰을 클라이언트에 전달합니다. 자체 토큰 엔드포인트에 대한 요청을 인증하고, 무제한 게이트웨이가 되지 않도록 사용 제한을 적용하세요.
마이크 동의, 녹음 제어, 연결 상태를 인터페이스에 명확히 표시하세요. 연결 손실을 명시적으로 처리하고, 오래된 재생을 중지하며, 이미 완료되었을 수 있는 동작을 재실행하지 않도록 하세요.
음성 사용과 커스텀 통합은 별도 비용을 발생시킬 수 있습니다. 이 튜토리얼에 관련된 공개 요금은 실시간 세션과 텍스트 입력이며, 독립형 음성 인식 및 음성 생성 제품은 별도 서비스입니다.
요금 확인일: 2026년 10월 29일. 최신 요금은 공식 가격 페이지를 확인하세요.
예를 들어, 과금 대상 세션 500분은 기본 음성 요금으로 $40에 해당합니다. 이 견적에는 텍스트 입력, 선택적 도구, 전화 통신, 자체 인프라는 포함되지 않습니다. 짧은 테스트 세션으로 시작하고, 대화가 끝나면 유휴 연결을 종료하세요.
Grok Voice 3.0 API의 한 번의 완전한 턴부터 시작하세요: 연결, 세션 구성, 프롬프트 제출, 오디오 수신, 재생. 이 경로가 정상 동작하면 녹음 음성을 추가하고, 그 위에 마이크 캡처와 스트리밍 재생을 구축하세요. 대화와 오류 처리 경로가 안정된 이후에 비즈니스 도구를 도입하세요.