# 1. POST → 202 Accepted (request_id 반환)
POST /api/v1/ns/{ns}/gpu/stt
  Content-Type: multipart/form-data  또는 application/json (audio_b64)
  → 202 { "request_id": "stt-1710000000000-a1b2c3d4" }

# 2. GET 폴링 → 완료 시 200
GET /api/v1/ns/{ns}/gpu/stt/{request_id}
  → 202 { "status": "queued" }
  → 200 { "status": "completed", "transcript": "..." }

# 데이터 흐름
Client → POST /gpu/stt (오디오 bytes) → Redis Queue → STTWorker
  → Whisper large-v3 → transcript → Redis Outbox → Client

{
  "ok": true,
  "data": {
    "request_id": "stt-1710567890123-a1b2c3d4",
    "task_type":  "stt",
    "hint":       "text_recommended"   // 4KB 미만 업로드 시에만 포함 — JSON 모드 권장 힌트
  }
}

hint 필드는 multipart 업로드가 4KB 미만일 때만 응답에 포함됩니다 (요청은 거부되지 않음). 작은 페이로드에는 base64 JSON 모드가 효율적입니다.

// include_segments=false (기본)
{
  "ok": true,
  "data": {
    "request_id":       "stt-1710567890123-a1b2c3d4",
    "status":           "completed",
    "transcript":       "Ask not what your country can do for you...",
    "language":         "en",           // 감지된 언어
    "duration_seconds": 13.82,          // 오디오 길이
    "segments":         null,           // include_segments=false 시 null
    "model":            "Systran/faster-whisper-large-v3",
    "cached":           false,
    "elapsed_ms":      2350.0
  }
}

// include_segments=true
{
  "data": {
    "transcript": "Ask not what your country...",
    "segments": [
      { "id": 0, "start": 0.0, "end": 3.5, "text": "Ask not what your country", "confidence": null },
      { "id": 1, "start": 3.5, "end": 6.2, "text": "can do for you", "confidence": null },
      ...
    ]
  }
}

# Multipart 모드 (권장 — 대용량 오디오)
curl -X POST https://localhost:1443/api/v1/ns/HRM/gpu/stt \
  -k \
  -H "X-API-Key: <your-key>" \
  -F "[email protected]" \
  -F "language=ko" \
  -F "include_segments=true"

# JSON 모드 (소용량)
curl -X POST https://localhost:1443/api/v1/ns/HRM/gpu/stt \
  -k \
  -H "X-API-Key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"audio_b64":"'"$(base64 -w0 audio.mp3)"'","language":"en"}'

# 결과 조회 (폴링)
curl https://localhost:1443/api/v1/ns/HRM/gpu/stt/stt-xxx -k \
  -H "X-API-Key: <your-key>"

# 결과 조회 후 자동 삭제
curl "https://localhost:1443/api/v1/ns/HRM/gpu/stt/stt-xxx?auto_clear=true" \
  -k -H "X-API-Key: <your-key>"

Redis Pub/Sub으로 완료 알림을 수신 후 즉시 인식 결과를 전송합니다. STT는 오디오 길이에 따라 처리 시간이 길어지므로 폴링보다 이 방식이 적합합니다.

// 인증: Sec-WebSocket-Protocol 헤더로 API 키 전달 (URL 쿼리 미지원)
// 브라우저: new WebSocket(url, ["redgx_ak_hrm_..."])
wss://<host>/api/v1/ns/HRM/gpu/stt/stt-xxx/wait?timeout=120          // 장시간 오디오는 최대 120s 권장

// 완료 — REST GET과 동일 구조
{ "ok": true, "data": { "request_id": "stt-...", "status": "completed",
    "transcript": "인식된 텍스트 전체", "language": "ko",
    "duration_seconds": 13.82, "segments": null,
    "model": "Systran/faster-whisper-large-v3", "cached": false, "elapsed_ms": 1850.0 } }

// 실패
{ "ok": true, "data": { "request_id": "stt-...", "status": "failed", "error": {...} } }

// 인증 실패 → HTTP 403 (upgrade 거부, accept 전 — 4001 close 프레임 미전송)
// Not Found    → { "ok": false, "error": { "code": "GPU_NOT_FOUND" } } + close(4004)
// Timeout      → { "ok": false, "error": { "code": "GPU_TIMEOUT" } }  + close(4008)