Soniox Speech-to-Text

Cloud speech-to-text API with real-time WebSocket streaming and async file transcription. Supports 60+ languages, speaker diarization, live translation, and custom vocabulary context.

API Structure

Two main APIs:

| API | Transport | Model | Use Case | |-----|-----------|-------|----------| | Real-Time | WebSocket wss://stt-rt.soniox.com/transcribe-websocket | stt-rt-v4 | Live audio streaming, token-by-token results | | Async | REST https://api.soniox.com/v1/ | stt-async-v4 | Pre-recorded files, batch processing |

Authentication: Authorization: Bearer <API_KEY> header (or api_key query param for WebSocket).

Quick Start — Real-Time WebSocket

1. Connect to wss://stt-rt.soniox.com/transcribe-websocket?api_key=YOUR_KEY
2. Send JSON config: {"model": "stt-rt-v4", "audio_format": "pcm_s16le", "sample_rate": 16000}
3. Stream raw audio bytes
4. Receive JSON tokens: {"tokens": [{"text": "hello", "is_final": true, "start_ms": 100, "end_ms": 500}]}
5. Close connection when done

Key token fields: text, is_final (false=provisional, true=confirmed), start_ms, end_ms, confidence, speaker (if diarization enabled), language (if language ID enabled).

Quick Start — Async REST

# Upload and transcribe
curl -X POST https://api.soniox.com/v1/transcriptions \
  -H "Authorization: Bearer $API_KEY" \
  -F model=stt-async-v4 \
  -F audio_file=@recording.mp3

# Poll for result
curl https://api.soniox.com/v1/transcriptions/{id} \
  -H "Authorization: Bearer $API_KEY"

Configuration Options (Both APIs)

Common parameters sent in start config (real-time) or request body (async):

| Parameter | Type | Description | |-----------|------|-------------| | model | string | stt-rt-v4 or stt-async-v4 | | language_hints | string[] | ISO 639-1 codes to improve accuracy | | language_hints_strict | bool | Restrict recognition to hinted languages | | enable_language_identification | bool | Detect language per token | | enable_speaker_diarization | bool | Label speakers (up to 15) | | translation | object | Translation config: {"type": "one_way", "target_language": "fr"} or {"type": "two_way", "language_a": "en", "language_b": "fr"} | | context | object | Domain context (see below) | | max_endpoint_delay_ms | int | 500-3000ms, semantic endpoint detection (real-time only) |

Context Object Format

{
  "context": {
    "general": [
      {"key": "domain", "value": "Healthcare"},
      {"key": "topic", "value": "Medical Consultation"}
    ],
    "text": "Background: Patient discussing cardiac symptoms...",
    "terms": ["myocardial infarction", "stent", "angioplasty"],
    "translation_terms": [
      {"source": "stent", "target": "стент"}
    ]
  }
}

Max 8000 tokens.

Reference Files

Read these based on the specific task:

| File | When to Read | |------|-------------| | references/realtime.md | WebSocket protocol details, token streaming, finalization, keepalive, error codes | | references/async-api.md | REST endpoints, file upload, job polling, webhooks, file management | | references/features.md | Languages list, diarization details, context format, models, timestamps | | references/sdks.md | Python/Node/Web SDK usage, code patterns, client initialization | | references/integrations.md | Direct/Proxy stream patterns, Vercel AI, TanStack, Twilio, n8n, data residency, security |

Native Swift/macOS Integration

Soniox has no native Swift SDK. For macOS/iOS apps, connect via raw WebSocket:

// URLSessionWebSocketTask approach
let url = URL(string: "wss://stt-rt.soniox.com/transcribe-websocket?api_key=\(apiKey)")!
let task = URLSession.shared.webSocketTask(with: url)
task.resume()

// Send start config
let config = """
{"model":"stt-rt-v4","audio_format":"pcm_s16le","sample_rate":16000}
"""
task.send(.string(config)) { error in /* handle */ }

// Stream audio bytes from microphone
task.send(.data(audioBuffer)) { error in /* handle */ }

// Receive tokens
func receiveNext() {
    task.receive { result in
        switch result {
        case .success(.string(let json)):
            // Parse tokens from JSON
            break
        case .failure(let error):
            // Handle error
            break
        default: break
        }
        receiveNext() // Continue receiving
    }
}

Audio format: Send raw PCM signed 16-bit little-endian at 16kHz mono for best results. The API also auto-detects encoded formats (mp3, ogg, flac, wav, etc.).

Rate Limits

| Limit | Real-Time | Async | |-------|-----------|-------| | Requests/min | 100 | 100 | | Concurrent | 10 connections | 100 pending jobs | | Max duration | 300 min/session | — | | Storage | — | 10GB, 1000 files | | Total transcriptions | — | 2000 |

Data Residency

Regional endpoints available:

| Region | Real-Time Endpoint | Async Endpoint | |--------|-------------------|----------------| | US (default) | stt-rt.soniox.com | api.soniox.com | | EU | stt-rt.eu.soniox.com | api.eu.soniox.com | | Japan | stt-rt-jp.soniox.com | api.jp.soniox.com |