Skip to navigation

Create transcription

Upload one audio file and transcribe it with Finch. Send finch_indic_1.0 to https://in.api.murf.ai and finch_global_1.0 to https://us-east.api.murf.ai. A model or language served by the other host returns 400 with redirect_url. Authenticate with the api-key header. xi-api-key, Authorization: Bearer, and the api_key query parameter also work; if more than one is sent, the query parameter is used, then the api-key or xi-api-key header, then Bearer. Prefer the api-key header. The query parameter puts the key in URLs and logs. POST /v1/transcription/upload calls this same handler; use this path. Without webhook, the call returns 200 with the transcript. If the job is still running after 20 seconds, the server sends the 200 headers and then a space every 10 seconds until the JSON is ready. A failure after those headers is a detail object in that same body. The synchronous wait stops at 600 seconds and the job keeps running; poll it with the transcription_id. With webhook=true the call returns 202, and Murf later POSTs the result to webhook_url. That POST is not signed. Set a hard-to-guess webhook_url. See the File transcription guide for the webhook body, retries, and polling.

Headers

api-keystringOptional

Your Murf API key. xi-api-key, Authorization: Bearer, and the api_key query parameter also authenticate this call. If more than one is sent, the query parameter is used, then the api-key or xi-api-key header, then Bearer. Avoid the query parameter: the key is stored in URLs and access logs.

Request

This endpoint expects a multipart form containing a file.
filefileRequired

Audio file. WAV, FLAC, or OGG (Vorbis or Opus). M4A, AAC, MP4, and WebM cannot be decoded. Stereo is mixed down to mono and the audio is resampled to 16 kHz. Maximum upload 1 GB. Maximum audio length 3600 seconds.

modelenumOptional

Required, unless model_id is sent. finch_indic_1.0 on in.api.murf.ai, or finch_global_1.0 on us-east.api.murf.ai.

Allowed values:
model_idenumOptional
Alias for model.
Allowed values:
language_codestringOptional

A language tag for the model, such as hi or en_IN. Omit it, or send auto, to detect the language.

keytermslist of stringsOptional
Phrases to boost. Repeat the form field once per phrase. There is no strength setting.
timestamps_granularityenumOptionalDefaults to word
word includes words. none omits words.
Allowed values:
bvcbooleanOptionalDefaults to false
Beta. true removes background voices before transcription. Adds about 3 to 4 minutes of processing per hour of audio. If the enhancement pool is busy, the file is transcribed without it. Included in the Speech to Text price.
zero_retentionbooleanOptional
Workspace setting. A request cannot turn it off. When it is on, the audio file is not stored. The transcript remains available for 24 hours.
webhookbooleanOptionalDefaults to false

Beta. true returns 202 and delivers the result to webhook_url.

webhook_urlstringOptional

Required when webhook is true. Murf POSTs the result here. The request is not signed. Use a hard-to-guess URL.

webhook_metadatastringOptional
A JSON string. Returned unchanged on the webhook.

Response

Transcript. After the early 200 headers on a long job, this body can instead be a detail error. Check for detail before reading text.
transcription_idstringOptional
language_codestringOptional
language_probabilitydoubleOptional
textstringOptional
Empty when the file contains no speech. That is a successful transcript.
audio_duration_secsdoubleOptional
wordslist of objectsOptional

Omitted when timestamps_granularity is none.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
413
Content Too Large Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error
504
Gateway Timeout Error