Transcribe audio

Request

POST https://router.speko.dev/v1/stt/transcriptions

The body is multipart/form-data with exactly two parts, in this order:

1. request — a JSON document (at most 1 MiB)
2. audio — WAV containing PCM s16le, or raw PCM s16le with an audio object in the request part

Part order is load-bearing: the idempotency content hash is defined over the parts in this order, and extra or reordered parts are rejected.

curl -s https://router.speko.dev/v1/stt/transcriptions \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'request={"routing":{"mode":"auto","objective":"quality"},"language":"en"};type=application/json' \
  -F 'audio=@interview.wav;type=audio/wav'

The request is held open until the transcript is ready. For recordings longer than a few minutes, or larger than the selected model's limit, use transcription jobs instead — they take audio of any length and deliver to a webhook.

The request part

The options object

Options are provider-neutral asks. They fail closed: a request routed to a model that cannot honor an option is refused with 400 capability_unsupported naming the option, never answered 200 with the feature silently missing — a diarization request served by a model that cannot diarize is indistinguishable from a one-speaker recording, so nobody would ever notice. GET /v1/models advertises each STT model's capabilities; in automatic routing, models lacking a requested capability are skipped.

{
  "routing": {"mode": "explicit", "provider": "deepgram", "model": "nova-3"},
  "language": "en",
  "options": {
    "diarization": true,
    "keywords": ["Speko", "Router"],
    "provider_options": {"deepgram": {"numerals": true, "smart_format": true}}
  }
}

Response

{
  "text": "Good morning everyone, let's get started.",
  "segments": [
    { "text": "Good morning everyone, let's get started.", "start_ms": 0, "end_ms": 2900, "speaker": "0" }
  ],
  "route": { "provider": "deepgram", "model": "nova-3", "region": "us-east-1", "attempt_id": "ratt_..." },
  "usage": { "duration_ms": 3000 }
}

With "options": {"word_timestamps": true} on gemini-3.5-transcribe:

{
  "text": "Salom dunyo",
  "segments": [{ "text": "Salom dunyo", "start_ms": 120, "end_ms": 1000 }],
  "words": [
    { "text": "Salom", "start_ms": 120, "end_ms": 480 },
    { "text": "dunyo", "start_ms": 510, "end_ms": 1000 }
  ],
  "route": { "provider": "gemini", "model": "gemini-3.5-transcribe", "region": "us-east-1", "attempt_id": "ratt_..." },
  "usage": { "duration_ms": 1000 }
}

The same route facts are echoed in the Speko-Request-ID, Speko-Provider, Speko-Model and Speko-Region response headers.

How your audio is transcribed

Every STT model in the catalog is served one of two ways, and GET /v1/models?path=batch tells you which:

• Pre-recorded route. The upload is sent as one file to the provider's batch/asynchronous transcription API — Deepgram /v1/listen, AssemblyAI's Transcripts API, Soniox async, ElevenLabs Scribe, OpenAI /v1/audio/transcriptions, and so on. The whole recording is transcribed in one call, bounded by that API's documented limits. These are the models listed under path=batch, and the only models transcription jobs will use.
• Realtime-only. A few models exist only as live sockets (Deepgram Flux, Cartesia ink-2, OpenAI gpt-live-transcribe, Palabra). The Router still transcribes short uploads on them by replaying the audio into the socket, bounded to 60 seconds — the most a realtime socket reliably keeps up with when fed faster than real time. They are omitted from path=batch and refused for jobs.

Either way the Router checks that the transcript actually covers the audio: a response whose last timed segment stops well short of the recording while speech continues is refused as a retryable provider_error rather than returned — and, in automatic mode, triggers failover.

Limits

There is no universal 25 MiB transcription cap. Each model's limit is the bound of its provider's pre-recorded API on one upload — decoded PCM bytes, duration, or both. Query GET /v1/models?path=batch and read batch_audio_limits for the authoritative values in your region. Current limits:

On this endpoint a recording over the limit is refused, not split:

• With automatic routing, models that cannot accept the recording are skipped. If no compatible model remains, the Router returns 413 payload_too_large before admission or provider contact.
• With explicit routing, a recording over the selected model's limit returns 413 payload_too_large before admission or provider contact — the hint names the limit and suggests GET /v1/models?path=batch.
• Recordings that exceed every model's limit belong on transcription jobs, which chunk them.

Other bounds:

• A deployment may apply an additional safety ceiling. This is an operational override, not a provider capability, so it is not included in batch_audio_limits.
• Batch audio is staged on temporary disk. If the Router task has no staging capacity, it returns retryable 429 concurrency_exhausted; this is capacity pressure, not a file-size limit.
• The canonical WAV transport has a format boundary of 4,294,967,258 decoded PCM bytes (about 4 GiB) for every provider.
• This endpoint accepts WAV (PCM s16le) and described raw PCM only. Anything else — including MP3, M4A, OGG, FLAC and WebM — returns 415 unsupported_media; so does a rate or channel layout the pinned model does not accept — the hint lists what it does. Transcription jobs decode compressed formats for you.
• The whole request body must complete within the 2-minute read deadline.
• Metering is by audio duration, rounded up to whole seconds. There is deliberately no usage header on STT responses — the usage object in the body is authoritative.
• In auto mode a provider failure before results triggers transparent failover.