xAI Grok 4.3 개발자 가이드 — Speech-to-Text·Text-to-Speech API 실전 활용

Grok STT API — Python 배치 처리
import anthropic

client = anthropic.Anthropic(
    api_key="your-xai-api-key",
    base_url="https://api.x.ai/v1"
)

# 배치 방식 — 파일 업로드 후 트랜스크립션
with open("meeting.mp3", "rb") as f:
    response = client.audio.transcriptions.create(
        model="grok-audio-v1",
        file=f,
        language="ko",             # 한국어 지정 (생략 시 자동 감지)
        timestamp_granularities=["word"],  # 단어 수준 타임스탬프
        response_format="verbose_json"
    )

print(response.text)
# 타임스탬프 접근
for word in response.words:
    print(f"{word.word}: {word.start:.2f}s - {word.end:.2f}s")

Grok STT API — JavaScript 실시간 스트리밍
// WebSocket 스트리밍 — 실시간 트랜스크립션
const ws = new WebSocket(
  'wss://api.x.ai/v1/audio/transcriptions/stream',
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
)

ws.onopen = () => {
  ws.send(JSON.stringify({
    model: 'grok-audio-v1',
    language: 'ko',
    diarize: true  // 화자 분리 활성화
  }))
  // 마이크 오디오 스트림 연결
  startMicrophoneCapture((chunk) => ws.send(chunk))
}

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  if (data.type === 'transcript') {
    console.log(`[화자 ${data.speaker}] ${data.text}`)
  }
}

Grok TTS API — 감정 태그 활용
import anthropic
import base64

client = anthropic.Anthropic(
    api_key="your-xai-api-key",
    base_url="https://api.x.ai/v1"
)

# 감정 표현 태그 사용 예시
text = """
안녕하세요, 오늘 업데이트를 소개해드리겠습니다. [pause]
<excited>이번 릴리즈에서 성능이 두 배 향상됐습니다!</excited>
[sigh] 물론 마이그레이션이 필요하긴 하지만... [laugh]
걱정 마세요, <whisper>생각보다 쉽습니다.</whisper>
"""

response = client.audio.speech.create(
    model="grok-tts-v1",
    voice="Ara",       # Ara / Eve / Leo / Rex / Sal
    input=text,
    response_format="mp3"  # mp3 / wav / flac / opus
)

# 파일 저장
with open("output.mp3", "wb") as f:
    f.write(response.content)

print(f"생성된 오디오: {len(response.content) / 1024:.1f} KB")

Voice Agent API — 기본 구조 (JavaScript)
// Grok Voice Agent — STT + LLM + TTS 올인원 파이프라인
const ws = new WebSocket(
  'wss://api.x.ai/v1/voice/agent',
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
)

ws.onopen = () => {
  // 세션 설정
  ws.send(JSON.stringify({
    type: 'session.create',
    model: 'grok-4.1-fast',      // 추론 모델 지정
    voice: 'Leo',                 // TTS 음성
    language: 'ko',
    system_prompt: '당신은 개발자 지원 어시스턴트입니다.',
    turn_detection: {
      type: 'server_vad',         // 서버 측 음성 감지
      silence_duration_ms: 500
    }
  }))
}

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)
  switch (msg.type) {
    case 'transcript.partial':
      // 실시간 텍스트 자막
      updateSubtitle(msg.text)
      break
    case 'audio.delta':
      // TTS 오디오 스트리밍
      audioPlayer.appendChunk(msg.audio)
      break
    case 'agent.message':
      // 최종 응답 텍스트
      addToConversation(msg.content)
      break
  }
}