---
title: "Transcribe raw audio with cross-provider routing"
method: POST
path: "/v1/transcribe"
---

# Transcribe raw audio with cross-provider routing

`POST /v1/transcribe`

Query parameters beyond the ones documented here are forwarded to the selected provider where its contract reads them, as they always have been; the transcription options below are consumed by the router instead.

## Query parameters

- `diarize` boolean
- `word_timestamps` boolean
- `smart_format` boolean
- `detect_language` boolean
- `language_hints` string

## Headers

- `X-Speko-Objective` 'latency' | 'quality' | 'cost' | 'balanced'
- `X-Speko-Language` string
- `X-Speko-Allow` string
- `X-Speko-Deny` string
- `X-Speko-Max-Price` number
- `X-Speko-Provider-Options` string

## Response `200`

Normalized transcription

- Transcription — Normalized transcript. text is always present. Every other field is additive and appears only when the provider that served the request supplied it: a field the provider has no contract for is omitted, never sent as null. Providers differ, and failover can change which one answers, so treat every field but text as optional per response.
  - `text` string, required
  - `language` string — Language the provider reported for this audio, in the provider's own spelling. Present only for providers that report one.
  - `duration` number — Length of the audio in seconds, when the provider measured it.
  - `confidence` number — Provider confidence in the whole transcript, 0 to 1.
  - `words` TranscriptionWord[] — Word-level timing in seconds. Omitted for providers that return none. A word the provider sent without offsets is omitted rather than published at 0.
    - `text` string, required
    - `start` number, required — Seconds from the start of the audio.
    - `end` number, required — Seconds from the start of the audio.
    - `confidence` number
    - `speaker` string — Speaker label in the serving provider's own vocabulary, which differs per provider: Deepgram numbers speakers, AssemblyAI letters them, ElevenLabs prefixes them. Present only when the provider labelled speakers. Labels are comparable within one response, not across providers.
  - `segments` TranscriptionSegment[] — Provider utterances, or speaker turns for providers that publish words rather than utterances. Omitted when the provider supplies neither.
    - `text` string, required
    - `start` number, required — Seconds from the start of the audio.
    - `end` number, required — Seconds from the start of the audio.
    - `speaker` string — Speaker label in the serving provider's own vocabulary, which differs per provider: Deepgram numbers speakers, AssemblyAI letters them, ElevenLabs prefixes them. Present only when the provider labelled speakers. Labels are comparable within one response, not across providers.
    - `language` string — Language of this segment, for providers that report code-switching per segment.
    - `confidence` number

## Other responses

- `422` — No available provider supports a requested transcription feature on the transport in use. error.details names the feature and the transport. The router refuses rather than answering without the feature, because a transcript with no speakers in it is indistinguishable from a recording of one speaker. Retrying does not help: widen X-Speko-Allow, drop the option, or use the other transport.
- `502` — Every attempted upstream failed before the router could complete the request. Route, reason, and failover-count headers are present; X-Speko-First-Byte-Ms is omitted.
- `default` — Router-generated errors use the Speko JSON error schema. A non-retryable upstream 4xx is passed through after response-header sanitization with its upstream status, media type, and body, which can be non-JSON.

---

[API](https://skmtc.net/speko/apis/speko-voice-router-api.md) · [All operations](https://skmtc.net/speko/apis/speko-voice-router-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/speko/speko-voice-router-api/versions/278edfaef74c/schema)