Platform docs
Get API key
Speech to text

Transcribe audio

POST /v1/speech-to-text

Upload an audio or video file and get its transcript back in the same response. The connection stays open while the file is decoded and transcribed; set a client timeout of several minutes for long files.

Billing is per started second of audio, at the model's hourly price, and only for requests that return 200. Errors and refused requests are free, and so is a request you cancel by closing the connection before its transcript is ready. Once it is, the request is billed even if the connection closes before the response arrives. An organization that cancels more than two hours of audio within an hour is answered 429 until the hour is over.

Limits

  • Files up to 250 MB, with between 0.1 seconds and 1 hour of audio.
  • An upload has 30 minutes to arrive, and must average at least 16 KB per second: one slower than that is refused after 20 seconds.
  • Requests per minute and requests at once depend on your organization's tier, shown under Settings in the console. Past either, the API answers 429 with a Retry-After header.

Authorization

Required. Send your API key in one of these headers.

Authorization: Bearer
header

Your API key, Authorization: Bearer kp_live_.... Create and revoke keys under API keys in the console; a key belongs to the organization and spends its credits. Keys start with kp_live_ and carry a checksum, so secret scanners can recognise them. Keep them server-side.

xi-api-key
header

The same API key in the header the ElevenLabs SDKs send. An ElevenLabs client can keep it; it still needs a Klang model_id and a language_code.

Body

multipart/form-data

fileREQUIRED
file

The audio, as a file part. Any common audio or video format works (MP3, WAV, M4A, AAC, FLAC, OGG, Opus, WebM, MP4 and others); the format is read from the content, not the file name. At most 250 MB and 1 hour of audio, and at least 0.1 seconds. Split longer recordings and send the parts.

model_idREQUIRED
"pianissimo" · "pianissimo_pro"
  • pianissimo: fast, accurate transcription.
  • pianissimo_pro: higher accuracy, and the only model that takes keyterms. Priced higher for Swedish and Danish, where it adds a language model; see the console's Models page. For the languages served by Parakeet it adds beam search and keyterms only, and costs the same as pianissimo.
language_codeREQUIRED
"bg" · "cs" · "da" · "de" · "el" · "en" · "es" · "et" · "fi" · "fr" · "hr" · "hu" · "it" · "lt" · "lv" · "mt" · "nl" · "pl" · "pt" · "ro" · "ru" · "sk" · "sl" · "sv" · "uk"

The spoken language, as a two-letter ISO 639-1 code. The API also takes it in upper case, but lower case, as listed here, is the canonical form.

language code model
Swedish sv Pianissimo (fine-tuned)
Danish da Pianissimo (fine-tuned)
Bulgarian, Croatian, Czech, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Ukrainian bg hr cs nl en et fi fr de el hu it lv lt mt pl pt ro ru sk sl es uk Parakeet parakeet-tdt-0.6b-v3

Swedish and Danish audio is transcribed as that language. Parakeet takes no language: it transcribes whichever of its languages it hears, so the code picks the model and the price, and is returned as given.

keyterms
array of string

Words and phrases to recognise more reliably, such as names, products and jargon. A hint, not a replacement list: a term only appears where it was said. pianissimo_pro only. Send the field once per term. Each term is at most 50 characters and 5 words, without < > { } [ ] \ or control characters; all terms together are at most 64 KB.

file_format
"other" · "pcm_s16le_16"

pcm_s16le_16 when the file is raw 16 kHz, mono, 16-bit little-endian PCM with no header. It skips decoding, so it is the fastest input. Anything else is other. To make it with ffmpeg: ffmpeg -i in.mp4 -ac 1 -ar 16000 -f s16le out.pcm.

enable_logging
boolean

Accepted for ElevenLabs compatibility, as this form field or as the enable_logging query parameter the ElevenLabs SDKs send. It changes nothing: Klang never stores your audio or transcript, and keeps each request's metadata (file size, audio length, model, language, status) for billing either way.

Response

The transcript.

language_code
string

The language_code you sent, in lower case.

language_probability
number

Always 1, since you name the language.

text
string

The whole transcript, punctuated.

words
array of object

The transcript word by word, with the gaps between words as spacing items. Words carry their punctuation.

↳text
string
↳start
number

Start, in seconds from the beginning of the audio.

↳end
number

End, in seconds from the beginning of the audio.

↳type
"word" · "spacing"
transcription_id
string · uuid

The request's id, the same as the X-Request-Id header.

model_id
"pianissimo" · "pianissimo_pro"
  • pianissimo: fast, accurate transcription.
  • pianissimo_pro: higher accuracy, and the only model that takes keyterms. Priced higher for Swedish and Danish, where it adds a language model; see the console's Models page. For the languages served by Parakeet it adds beam search and keyterms only, and costs the same as pianissimo.
audio_seconds
number

Length of the audio, in seconds. You are billed for it rounded up to a whole second.

X-Request-Id
header

The request's id. Include it when you contact support.

Errors

An error response has this body:

error
object
↳type
"invalid_request_error" · "authentication_error" · "billing_error" · "rate_limit_error" · "api_error"

The kind of error. Decide what to do on type and code, not on message.

↳code
string

What went wrong, stable across releases.

↳message
string

A human-readable explanation. It can change.

400

The request is invalid. Codes:

code meaning
invalid_body The body is not multipart/form-data, or a field is in a charset the API cannot read.
missing_parameter model_id or language_code is missing.
missing_file No file part, or it is empty.
invalid_model model_id is not a model.
unsupported_language language_code is not one of the 25 languages.
invalid_file_format file_format is not other or pcm_s16le_16.
unknown_parameter The form has a field the API does not know.
unsupported_parameter An ElevenLabs option Klang does not support yet (diarization, webhooks, …), or keyterms with pianissimo.
too_many_keyterms More than 1000 keyterms, or over 64 KB together.
invalid_keyterm A keyterm is too long or has a forbidden character.
unreadable_audio The file could not be read as audio.
empty_audio The file has less than 0.1 seconds of audio.
audio_too_long The audio is longer than your limit (1 hour).
too_many_fields The form has too many fields.
field_too_large A text field is too long.
401

No usable API key. Codes: missing_api_key, invalid_api_key, api_key_revoked, api_key_expired.

402

insufficient_credits: your organization is out of credits. Add credits or turn on auto top-up under Billing in the console.

408

upload_timeout: the upload took longer than 30 minutes. upload_too_slow: the upload averaged under 16 KB per second, checked every 20 seconds. Check the connection, or send a smaller file.

413

file_too_large: the file is over your organization's limit (250 MB).

429
Retry-After

Over your organization's limits. Wait Retry-After seconds and try again.

  • rate_limit_exceeded: too many requests in the last minute.
  • too_many_concurrent_requests: too many requests in flight at once.
  • too_many_cancelled_requests: over two hours of audio cancelled within an hour. Retry-After is 600.
  • too_many_refused_requests: 60 requests refused within a minute (out of credits, or over these limits). Retry-After is 60.
500

internal_error: something went wrong on Klang's side. Retry with backoff.

502

transcription_failed: the transcription failed. Retry with backoff; you are not billed.

503
Retry-After

overloaded: transcription is at capacity. Wait Retry-After seconds and try again; you are not billed.