Skip to main content
POST
Audio Transcriptions
Synchronous endpoint. Send audio in, get the transcript back in one call. Two input modes:
  • Mode 1 — File upload (multipart/form-data, up to 25 MB). Drop-in OpenAI Whisper replacement.
  • Mode 2 — URL fetch (application/json, audio_url up to 100 MB on whisper-v3-turbo and 25 MB on every other model, https only). Kyma extension — pass a public URL, Kyma fetches the bytes upstream so you don’t proxy them through your client.
The same request also benefits from automatic never-die failover when the primary model has a transient hiccup — see Automatic failover (never-die STT).

Choosing a mode

Mode 2 is a Kyma extension. It is not part of the OpenAI Whisper API. The OpenAI Python and Node SDKs only support multipart upload — for audio_url mode, use requests (Python), fetch (Node), or curl.

Request

Both modes accept the same set of model / language / format parameters.

Mode 1 — multipart upload

file
required
Audio file. Accepted formats: mp3, wav, m4a, ogg, flac, webm — the set every transcription model accepts, measured against each one. ogg and webm mean Opus in those containers, which is what browser MediaRecorder emits. Max 25 MB. ~30 minutes of mono 16kHz mp3 fits comfortably.The part’s Content-Type may be generic (application/octet-stream, or missing) — the file extension decides. Anything else is refused with 415 unsupported_audio_type before any charge.
string
default:"transcribe"
Choose by alias or SKU:
  • transcribe (default) → whisper-v3-turbo — fastest and cheapest, $0.0009/min. Best for high-volume bulk transcription.
  • transcribe-quality → gpt-4o-mini-transcribe-2025-12-15 — premium accuracy on noisy / conversational / code-switching audio (Vi/En mixing), $0.00405/min. Retiring 2027-02-26 — see gpt-transcribe below.
  • gpt-transcribe — OpenAI’s current premium STT and the replacement it names for the model above, $0.006075/min. Opt-in by SKU; the transcribe-quality alias is unchanged.
  • gemini-3.5-transcribe — Google file STT, $0.00675/min. Opt-in by SKU; the transcribe alias is unchanged.
Not every model returns per-segment timestamps — see Segment timestamps by model before choosing verbose_json, srt or vtt.
  • Or pin a specific SKU directly (e.g. whisper-v3-turbo, gpt-transcribe, gpt-4o-mini-transcribe-2025-12-15, gemini-3.5-transcribe). See Audio models and Model aliases.
string
ISO-639-1 code (e.g. en, vi, ja). Optional — both providers auto-detect when omitted. Supplying it improves accuracy on short clips.
string
One of: json, verbose_json, text, srt, vtt. JSON formats embed a billing block in the response body. text returns the bare transcript and srt / vtt return subtitle files; for those three, billing rides on X-Kyma-* response headers so the body stays a clean transcript or subtitle file.verbose_json, srt and vtt need per-segment timestamps. On a model that returns a plain transcript they are refused with 400 segments_unsupported — before any provider call, so nothing is charged. See Segment timestamps by model.
number
default:"0"
Sampling temperature 0–1. Default 0 (deterministic).
string
Optional priming text. Use it to nudge the model toward known proper nouns, acronyms, or domain vocabulary in your audio.

Mode 2 — JSON audio_url

string
required
Public HTTPS URL of the audio file. Kyma fetches the bytes upstream — no need to download and re-upload from your client. Max 100 MB on whisper-v3-turbo; every other model, and the whisper-1 failover, fetches at most 25 MB and fails a larger file. http:// and other schemes are rejected to prevent SSRF / mixed-content. The bytes are fetched and passed to the model as the host serves them — Kyma does not inspect the URL’s Content-Type — so use one of the Mode 1 formats; anything else is the model’s own error.
string
default:"transcribe"
Same as Mode 1.
string
Same as Mode 1.
string
Same as Mode 1. Mode 2 still benefits from never-die failover (retry + the timestamp-preserving secondary); the plain-text tertiary tier is skipped in URL mode. See Automatic failover.
number
Same as Mode 1.
string
Same as Mode 1.

Response

200 OK with the transcript and a Kyma billing block.
string
The full transcript.
string
Detected language (full name, e.g. "English"). Like task, duration and segments, it is returned only with verbose_json, which only timestamp models serve. With json the body is text, model and billing, plus logprobs when you asked for them.
number
Audio duration in seconds (decoded from the file, not estimated). 0 only when the plain-text tertiary tier (gemini-3-flash-audio) served the request, which does not return duration.
array
Per-segment timestamps and text. Present when response_format is verbose_json and the model returns timestamps (supports_segments: true on /v1/models) — whisper-v3-turbo, or its failover whisper-1. A model without them cannot be asked for verbose_json at all (400 segments_unsupported).
string
The model SKU you requested, which is the one you are billed for. It stays the same when a failover model served; see X-Kyma-Fallback.
number
Minutes charged. Audio is billed in 1-minute increments, rounded up.
number
Final cost charged for this request.
number
Remaining balance after this charge.

Non-JSON formats

When response_format is text, srt, or vtt, the body is a plain transcript or subtitle file (no JSON envelope) and billing comes back on response headers (see below). srt returns a SubRip subtitle file (application/x-subrip; charset=utf-8); vtt returns a WebVTT file (text/vtt; charset=utf-8). Both are built from the same per-segment timestamps verbose_json exposes, so the timing matches across formats.

Segment timestamps by model

Only some transcription models return per-segment timestamps (segments[] with start, end, avg_logprob, no_speech_prob). The catalogue says which: GET /v1/models carries supports_segments on every transcription SKU, and a request for verbose_json / srt / vtt on a model without them is refused up front with 400 segments_unsupported and a suggested_models list. If you need timestamps or confidence per segment, use whisper-v3-turbo. Cutting a plain transcript into pseudo-segments client-side and estimating times from character counts produces invented timings — it is not something Kyma does for you.

Response headers

Returned on text, srt and vtt responses. json and verbose_json responses carry the same figures in the body’s billing block instead, and set none of these headers.

Automatic failover (never-die STT)

Transcription is never-die. On a transient hiccup with the primary model (default transcribe alias / whisper-v3-turbo SKU), Kyma transparently works through a failover chain so your request still completes — same request, same price, same response shape. You don’t opt in: it’s on by default. Why it matters. A single transcription request is normally a single point of failure — one transient hiccup and the pipeline built on top of it (a dub, a caption job, a voice agent) dies, leaving you to write retry and fallback logic yourself. Kyma absorbs that for you: the request either completes or fails honestly — never silently mangled. You ship the feature, not the plumbing. The chain is format-aware, because only some models preserve per-segment timestamps:
  1. Retry the primary once (short backoff). Absorbs the vast majority of transient blips, which recover immediately. Nothing in your response changes.
  2. Secondary — whisper-1. A timestamp-preserving model. Because it returns real per-segment timestamps, it serves every caller, including verbose_json, srt, and vtt.
  3. Tertiary — gemini-3-flash-audio. A plain-text transcription tier. Used only for plain-text transcripts (text / json) — it does not return segment timestamps, so callers that need them (verbose_json / srt / vtt) never route here. URL mode (audio_url) also skips this tier (it needs inline bytes).
If every tier is exhausted, you get a clean error (the chain genuinely had nothing left), not a leaked upstream message. Only genuine client errors fail fast. A bad file, a too-large upload, or an unsupported format (400 / 413 / 415 / 422) is surfaced immediately with no failover — failover is a reliability tool, not an error-hiding one. On transcribe, a rate limit on the primary model moves the request down the chain like any other hiccup. On the models that do not fail over, it returns 429 with code provider_rate_limited and a Retry-After header. You can see which tier served:
  • X-Kyma-Fallback header — the secondary model SKU that served, when a secondary served. It is set on text, srt and vtt responses only; a json or verbose_json response does not show that a failover happened.
  • segments is present whenever a timestamp-preserving model served (primary or whisper-1); absent only on the plain-text tertiary tier, where duration is also 0 (billed as the 1-minute minimum).
Only whisper-v3-turbo (the transcribe alias) has the chain. The other SKUs opt out — you chose that model, so Kyma won’t silently swap it. That covers the transcribe-quality alias (gpt-4o-mini-transcribe-2025-12-15), gpt-transcribe and gemini-3.5-transcribe. Their errors surface as 502 transcription_failed.

Pricing

Billed per minute, rounded up (a 5-second clip costs 1 minute). Failover transcriptions are billed at the same rate as the primary transcribe path — it doesn’t matter which tier ultimately served, you always pay the whisper-v3-turbo price. The Quality tier does not fall back (your choice of model is respected).

Errors

A transcription that ran is charged for the duration the provider measured, even if your balance fell below it while the file was being transcribed — the same rule /v1/chat/completions follows. The balance can go slightly negative for that one request; the next request is refused with 402 until you top up. Every transcription error that leaves you without a transcript carries error.suggested_models: up to three other transcription model ids, filtered to ones that can serve the format you asked for. They are suggestions — Kyma never swaps the model you named.

Examples

Pin a specific model

Just the transcript text (full never-die chain)

Returns the bare transcript. If the primary model has a transient hiccup, the request transparently completes via a secondary or tertiary tier and you’ll see X-Kyma-Fallback naming the model SKU that served.

URL mode — Node fetch

URL mode — Python requests

The OpenAI Python SDK only supports multipart uploads — use requests directly for Mode 2.

Python (OpenAI SDK — Mode 1 only)

See also

  • Audio Understand — the rest of the audio scene (tone, music, mood)
  • Audio models — SKUs behind the transcribe alias
  • Rate Limits — concurrency caps for audio endpoints
  • watch-cli — open-source CLI that uses these endpoints to give any agent eyes and ears for any social video