---
title: "Transcribe audio"
method: POST
path: "/v1/audio/transcriptions"
---

# Transcribe audio

`POST /v1/audio/transcriptions`

OpenAI-compatible multipart STT input. Speko rewrites or unwraps the request for eligible HTTP, WebSocket, or multi-step STT adapters and normalizes every supported transcript shape to the Transcription schema, whose only guaranteed field is text; audio compatibility can narrow the candidate set. An exact ru language hint narrows the candidate set further: it routes only to compatible OpenAI transcription models.

## 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`

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)