Speech-to-Text (Multimodal)

API reference

curl -X POST "https://__mock__/speech-to-text/transcribe" \  -F audio="string"

{
  "status": "success",
  "request_id": "req_stt_01hexample",
  "text": "Sample transcript for mock responses in the Playground.",
  "detected_language": "en-IN",
  "confidence": 0.94,
  "words": [
    {
      "word": "Sample",
      "start": 0,
      "end": 0.32
    },
    {
      "word": "transcript",
      "start": 0.35,
      "end": 0.88
    }
  ],
  "provider": "openai",
  "model": "whisper-1",
  "accuracy": "medium",
  "usage": {
    "audio_seconds": 4.2,
    "billed_seconds": 5
  }
}

{
  "detail": {},
  "message": "string"
}

{
  "detail": {},
  "message": "string"
}

{
  "detail": {},
  "message": "string"
}

{
  "detail": {},
  "message": "string"
}

{
  "error": "string"
}

Overview

The Speech-to-Text (STT) API is a single integration surface for audio → text with provider routing and policy-based controls. You choose a provider / model, set source language (default English), tune accuracy tier (low, medium, high), and optionally let the service pick language and routing dynamically based on tier, latency budget, and supported locales per provider.

[PLACEHOLDER FOR SCREENSHOT]

Key features

• Audio-first contract: Accept audio as required input with a stable multipart schema.
• Multi-provider routing: One contract; swap model without changing your client orchestration.
• Explicit or auto language: Pin language (BCP-47, for example en, en-IN, hi-IN) or use language_mode: auto for detection.
• Accuracy tiers: low, medium, high map to latency/cost/quality trade-offs and may constrain which providers run for a given locale.
• Dynamic language policy: Optional accuracy_language_policy ties tier to allowed auto-detect candidates or fallback order.
• Operational extras: Idempotency, callbacks for long jobs, timestamps, diarization hooks, and retention controls (see below).

Supported providers and popular models

The wrapper exposes provider (or model composite string provider:model_id) from commonly used stacks. Exact model_id strings are versioned in your environment’s model registry; this table lists representative families.

Benefit: You standardize on one request schema and one observability story while retaining access to best-in-class engines per locale and SLA.

Language model

1. Default: language: "en" (English) when omitted.
2. Explicit locale: Set language to a BCP-47 tag (for example en-IN, hi-IN).
3. Auto detection: Set language_mode": "auto". The service may return detected_language in the response.
4. Dynamic choice by accuracy: Set accuracy_language_policy so each accuracy tier defines allowed_languages, prefer_providers, or fallback_chain. Example: high → fixed en-IN + OpenAI/Azure; low → auto + streaming Deepgram with broad allowed_languages.

Accuracy tiers

Benefit: Product teams expose one slider; backend maps to provider capabilities and quota.

API contract (reference)

Call POST /speech-to-text/transcribe with Authorization: Bearer <token> and multipart/form-data. The OpenAPI block above is the source of truth for field names and enums. accuracy_language_policy is sent as a JSON string in multipart (same pattern as other stringified JSON fields in ML APIs).

HTTP

POST /speech-to-text/transcribe
Content-Type: multipart/form-data
Authorization: Bearer <token>

Request fields (conceptual JSON; use multipart parts or string fields per OpenAPI)

{
  "audio": "<binary or multipart file field>",
  "provider": "openai",
  "model": "whisper-1",
  "language": "en",
  "language_mode": "fixed",
  "accuracy": "medium",
  "accuracy_language_policy": {
    "high": { "language_mode": "fixed", "language": "en-IN", "provider_preference": ["azure", "openai"] },
    "low": { "language_mode": "auto", "allowed_languages": ["en", "hi", "ta"], "provider_preference": ["deepgram", "sarvam"] }
  },
  "enable_word_timestamps": true,
  "enable_diarization": false,
  "enable_pii_redaction": false,
  "callback_url": "https://example.com/stt-callback",
  "idempotency_key": "uuid-v4",
  "metadata": { "session_id": "abc123" }
}

Response

{
  "status": "success",
  "request_id": "req_01h...",
  "text": "Full transcript text.",
  "detected_language": "en-IN",
  "confidence": 0.93,
  "words": [{ "word": "Hello", "start": 0.12, "end": 0.34 }],
  "provider": "openai",
  "model": "whisper-1",
  "accuracy": "medium"
}

Wrapper capabilities (recommended)

• Unified authentication and per-tenant rate limits.
• Format normalization (WAV, MP3, M4A, FLAC) and sample-rate hints.
• Streaming WebSocket or SSE channel for low latency paths (provider-dependent).
• Fallback chain: If primary provider errors or rejects locale, try fallback_chain from policy.
• Cost and latency hints in response usage object (seconds billed, realtime_factor).
• Data retention TTL per request (retention_hours).
• Webhook signature (HMAC) on callbacks.
• Audit: Store hashes only when PII minimization mode is on.

Implementation

1. Obtain token: Use the same Bearer pattern as other KwikID APIs.
2. Choose path: Synchronous upload for short clips; callback_url for long interviews.
3. Set language: Start with language: "en"; expand to target locales; switch to language_mode: auto only when accuracy and policy allow.
4. Map accuracy: Align high with review workflows; use low for live agent assist.
5. Test matrix: For each provider, run gold audio in en, en-IN, and your top regional languages.
6. Monitor: Track WER proxies, p95 latency, and empty transcript rate by provider.

Error handling

Benefits

• Single integration for many STT backends.
• Predictable cost/quality via accuracy.
• Locale agility from English-first to broad Indian and global languages.
• Future-proofing as new model_id values are added to the registry.

Next steps

• Machine Learning API index
• API Suite index
• Facematch (when pairing voice with face journeys)