xAI Grok Voice
xAI Grok Voice
XaiRealtimeModel은 Grok Voice를 타입화된 서버 측 realtime 에이전트 루프로 가져와요. realtime 퀵스타트나 텍스트-음성 예제로 시작하세요.
출처: 문서
본문
설정
Grok Voice를 사용하려면 pydantic-ai-slim을 xai-realtime 옵션 그룹과 함께 설치하세요. xai-sdk와 함께, 이 번들은 openai 패키지도 포함해요. Grok Voice의 realtime API가 OpenAI Realtime 프로토콜의 이벤트 타입을 재사용하기 때문이에요:
pip install "pydantic-ai-slim[xai-realtime]"
uv add "pydantic-ai-slim[xai-realtime]"
xAI 모델 문서에서 설명한 대로 XAI_API_KEY를 설정하세요. provider='xai'를 사용하거나 api_key=를 가진 XaiProvider를 전달하세요. 커스텀 api_host는 지원되지 않고, xai_client=만으로 만든 프로바이더는 API 키가 필요하므로 WebSocket을 열 수 없어요.
모델 이름
grok-voice-latest 같은 Grok Voice ID나 고정된 grok-voice-think-* 모델을 사용하세요. grok-voice-latest는 xAI의 현재 플래그십을 따라 애플리케이션 아래에서 바뀔 수 있어요. 동작이 안정적이어야 할 때는 버전을 고정하세요. 표준 모델 목록은 공식 xAI 음성 문서를 사용하세요.
설정
XaiRealtimeModelSettings — 모델 실행 설정의 realtime 대응물 — 은 공유 설정을 확장해요:
from pydantic_ai.realtime.xai import XaiRealtimeModel, XaiRealtimeModelSettings
settings = XaiRealtimeModelSettings(
xai_voice='eve',
turn_detection={'sensitivity': 'low'},
input_transcription_model='auto',
)
model = XaiRealtimeModel('grok-voice-latest', settings=settings)
xai_voice는 프로바이더 음성을 선택해요. 설정하지 않으면 xAI가 자체 서버 측 기본값(현재 eve)을 고릅니다. 정확한 서버 VAD 임계값이나 자동 응답 동작을 위해 ServerVAD로 xai_turn_detection=을 설정하세요. 그것은 공유 turn_detection을 완전히 덮어써요. 푸시-투-토크에는 turn_detection=False를 설정하세요.
입력 전사는 기본 'auto'예요. 라이브 캡션에 묘사된 증가 델타와 달리, xAI는 이전 단어를 수정할 수 있는 누적 전사 스냅샷을 보내요. 그래서 캡션 UI는 델타를 덧붙이기보다 전체 TranscriptUpdate.transcript를 렌더링해야 해요.
Reasoning
grok-voice-latest와 grok-voice-think-* 모델은 공유 thinking 설정을 지원해요. 프로바이더는 'high'와 'none'만 노출해요. 활성화된 모든 effort는 'high'로 매핑되고, False는 'none'으로 매핑돼요. 다른 Grok Voice 모델은 설정을 무시해요.
기능 지원과 한계
| 기능 | 지원 | 참고 |
|---|---|---|
| 오디오 형식 | 전체 기능 지원 | 모노 PCM16, 24kHz 입력·출력 |
| 텍스트 출력 | 미지원 | Grok Voice는 항상 오디오를 생산 |
| 이미지 입력 | 미지원 | xAI는 이미지 입력을 문서화하지 않음; 현재 받아들여진 프레임은 거부되는 대신 조용히 무시됨 |
| 수동 턴 | 전체 기능 지원 | turn_detection=False + commit/create 동사 |
| 중단 | 제한된 매개변수 지원 | interrupt()는 작동; played_ms로 출력 자르기는 안 됨 |
| 입력 전사 | 전체 기능 지원 | 전용 프로바이더 경로; 기본 'auto' |
| 네이티브 툴 | 미지원 | 웹 기능에 로컬 폴백 구성 |
| 사용량 | 전체 기능 지원 | RunUsage.details의 오디오 토큰 버킷과 billable_audio_seconds |
| 상태 복원 재연결 | 전체 기능 지원 | 네이티브 재개는 재연결 정책과 함께 자동 |
프로바이더 무관 워크플로우는 오디오, 이미지, 전사, 턴과 중단, 툴, 연결 라이프사이클을 참고하세요.
게이트웨이
Grok Voice는 현재 Pydantic AI Gateway를 통해 제공되지 않아요. provider='xai' 또는 XaiProvider로 연결하세요.
세션 재개
ReconnectPolicy로 xAI는 상태 복원 재연결을 위한 네이티브 재개를 자동으로 활성화해요. 이전 턴을 복원하고 로컬 이벤트 스트림에서 프로바이더의 재생 버스트를 억제해요. 핸들은 메모리에 남고 다른 프로세스에서 재개할 수 없어요.
프로바이더 특유의 특이점
- Grok Voice는 항상 말해요. 프로필이
supports_text_output=False를 보고하므로output_modality='text'는 연결 전에UserError를 발생시켜요.SpeechPart에서 전사로 답을 읽으세요. - Pydantic AI는 xAI가 문서화하지 않기 때문에 출력 자르기를 미지원으로 보고해요. API는 현재
conversation.item.truncate를 조용히 받아들이지만 효과를 확인하거나 문서화하지 않아요. 그래서 로컬 재생을 플러시하고played_ms없이interrupt()를 호출하세요. - 프로토콜은 OpenAI Realtime과 닮았지만 기능 지원은 xAI 모델 프로필에서 와요. 모든 OpenAI 동작이 있다고 가정하지 마세요.