# Multispeaker STT API

Base URL: `https://api.stt.multispeaker.ganas.ai` (also `https://www.api.stt.multispeaker.ganas.ai`).

Create a client key in `/admin`; send it as `Authorization: Bearer YOUR_KEY`. HTTPS is required. Client keys support expiry, IP allowlists, concurrency limits, and requests-per-minute limits. Keys are shown once.

## File uploads

`POST /v1/audio/diarizations` accepts multipart field `file` (WAV, MP3, FLAC, or other FFmpeg-supported audio), at most 25 MiB and 60 seconds. The response includes `speakers`, chronological `segments` with `start`, `end`, `speaker`, `text`, and `is_low_confidence`, plus joined `text`. Nemotron 3 supports up to eight speakers. Segment speaker labels are generic IDs in first-arrival order. Overlapping speech can produce unreliable transcript text because the recognizer does not separate simultaneous voices.

```bash
curl --fail-with-body https://api.stt.multispeaker.ganas.ai/v1/audio/diarizations \
  -H "Authorization: Bearer $STT_API_KEY" -F 'file=@meeting.wav'
```

`POST /v1/audio/transcriptions` and alias `/transcribe` provide plain transcription for clips up to 30 seconds. Their response is the existing STT JSON object (text, duration, confidence flags). Supported transcription languages: English, Hindi, Marathi, Kannada, Telugu. Nemotron only identifies speakers; it does not recognize words or languages.

## Live transcription

`wss://api.stt.multispeaker.ganas.ai/v1/audio/transcriptions/ws` and alias `/ws/transcribe` accept the existing STT 16 kHz mono PCM16 protocol. Authenticate with `{"api_key":"..."}` as the first JSON frame, then send binary PCM frames (at most 65536 bytes each). The first server event is `ready`; finalized utterances arrive as `transcript` events. Send `{"event":"end"}` to flush. These live routes do not return speaker labels.

`/ws/telephony` accepts the existing 8 kHz mono mu-law JSON protocol. A `start` event must include a `callSid` or `streamSid` containing 1–95 letters, digits, underscores or hyphens. Poll `/calls/{call_id}/transcripts` with the same multispeaker client key. Call IDs are scoped to each client key. See the existing STT integration guide for the media event format.

## Health and errors

`GET /health` shows process liveness. `GET /ready` checks Nemotron plus the existing STT backend. 401/403 mean key or IP rejection; 413 means upload too large; 422 means duration or validation failure; 503 means model busy or backend unavailable. Retry 503 after a delay. Only one diarization job runs at a time. Audio and transcripts are not retained by this service; request metadata is kept for 30 days.