Skip to navigation

File transcription

Upload a recorded file and get one transcript, synchronously or by webhook.

File transcription sends one recorded file to Finch and returns one transcript. Use it for voicemail, call recordings, and other audio you already have. For live audio, use Streaming: that guide sends audio over a WebSocket and returns partial transcripts while the caller is speaking.

Files up to 1 hour, webhook delivery, and background voice cancellation (bvc) are Beta.

Endpoint

POST /v1/transcription/speech-to-text

Send Finch-Indic to India and Finch-Global to US East. model is required. model_id is an alias for the same field.

https://in.api.murf.ai/v1/transcription/speech-to-text
https://us-east.api.murf.ai/v1/transcription/speech-to-text
ModelHostLanguages
finch_indic_1.0in.api.murf.aiIndic languages and English (India). See Languages.
finch_global_1.0us-east.api.murf.aiEnglish and European languages. See Languages.

A model or language that belongs on the other host returns 400 with redirect_url set to that host.

POST /v1/transcription/upload calls the same handler. Use /v1/transcription/speech-to-text. The polling path is /v1/transcription/speech-to-text/transcripts/{transcription_id}.

Authentication

Send your API key in the api-key header. Speech to Text does not accept tokens from GET /v1/auth/token.

MethodExample
Header (use this)api-key: YOUR_API_KEY
Headerxi-api-key: YOUR_API_KEY
HeaderAuthorization: Bearer YOUR_API_KEY
Query?api_key=YOUR_API_KEY

If you send more than one, the api_key query parameter is used, then the api-key or xi-api-key header, then Authorization: Bearer. Leave the key out of the query string. Query parameters are stored in URLs and access logs.

Request

The body is multipart/form-data.

curl -X POST "https://us-east.api.murf.ai/v1/transcription/speech-to-text" \
-H "api-key: $MURF_API_KEY" \
-F "file=@recording.wav" \
-F "model=finch_global_1.0" \
-F "language_code=en"
FieldRequiredDescription
fileYesThe audio file. See Audio formats. A request without this field returns 422 before the API key is checked.
modelYesfinch_indic_1.0 or finch_global_1.0. You can send model_id instead.
language_codeNoA language tag from Languages, such as hi or en_IN. Omit it, or send auto, to detect the language.
keytermsNoA phrase to boost. Repeat the field once per phrase. There is no strength setting. See Keyword boosting.
timestamps_granularityNoword (default) or none. none omits words.
bvcNotrue removes background voices before transcription. Beta. This 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_retentionNoWorkspace setting. A request cannot turn it off. When it is on, the audio file is not stored. The transcript is still available for 24 hours.
webhookNotrue returns 202 immediately and delivers the result to webhook_url. Beta.
webhook_urlWhen webhook is setWhere Murf POSTs the result. Use a hard-to-guess URL. Webhooks are not signed.
webhook_metadataNoA JSON string. Murf returns it unchanged on the webhook.

For a file longer than about a minute, set webhook=true. A synchronous request depends on the connection staying open while the server sends keepalive bytes, and proxies can close that connection.

Audio formats

The server decodes the file, mixes stereo down to mono, and resamples the audio to 16 kHz.

Format
WAVSupported
FLACSupported
OGG (Vorbis or Opus)Supported
M4A, AAC, MP4, WebM400 Unable to decode audio file

Limits

LimitValueResponse
Upload size1 GB413
Audio length3600 seconds (1 hour)400, audio longer than 3600 seconds
Jobs running on one server8429 offline transcription capacity reached

The 8-job limit counts every in-flight file job on that server. Retry it with backoff. A separate account check returns 429 concurrency_limit_reached. See Rate Limits & Concurrency and Errors.

File transcription runs when the live streaming queue is idle, so a job can take longer while streaming traffic is high.

Synchronous response

A request without webhook=true waits and returns 200 with the transcript.

{
"transcription_id": "cb1594c2-d447-490a-9695-1a24be951495",
"language_code": "en",
"language_probability": 1.0,
"text": "Hello from Murf.",
"audio_duration_secs": 5.5,
"words": [
{ "text": "Hello", "start": 0.1, "end": 0.4, "type": "word" },
{ "text": " ", "start": 0.4, "end": 0.4, "type": "spacing" },
{ "text": "from", "start": 0.4, "end": 0.6, "type": "word" }
]
}

start and end are seconds from the start of the file. type is word or spacing. A file with no speech completes with an empty text. That is a successful transcript.

If the job is still running 20 seconds after the upload, the server sends the 200 headers and then a space every 10 seconds until the JSON is ready. Read the body before you treat the call as a success. After those headers, a failure arrives as JSON in the same 200 response:

{
"detail": {
"code": "transcription_failed",
"message": "None of the speech in the file could be transcribed",
"transcription_id": "cb1594c2-d447-490a-9695-1a24be951495"
}
}

Branch on detail.code when detail is an object. The message text can change.

The synchronous wait stops at 600 seconds. The body then includes the transcription_id, and the job keeps running. Poll it.

{ "detail": "offline transcription timed out", "transcription_id": "cb1594c2-d447-490a-9695-1a24be951495" }

Webhook

Beta. Set webhook=true and webhook_url. The upload returns 202 immediately:

{
"message": "transcription_started",
"request_id": "cb1594c2-d447-490a-9695-1a24be951495",
"transcription_id": "cb1594c2-d447-490a-9695-1a24be951495"
}

When the job finishes, Murf POSTs JSON to webhook_url with Content-Type: application/json and an X-Murf-Transcription-Id header. Check data.status first.

Success:

{
"type": "speech_to_text_transcription",
"data": {
"transcription_id": "cb1594c2-d447-490a-9695-1a24be951495",
"request_id": "cb1594c2-d447-490a-9695-1a24be951495",
"status": "completed",
"transcription": {
"transcription_id": "cb1594c2-d447-490a-9695-1a24be951495",
"language_code": "en",
"language_probability": 1.0,
"text": "Hello from Murf.",
"words": [
{ "text": "Hello", "start": 0.1, "end": 0.4, "type": "word" },
{ "text": " ", "start": 0.4, "end": 0.4, "type": "spacing" },
{ "text": "from", "start": 0.4, "end": 0.6, "type": "word" }
],
"audio_duration_secs": 5.5
},
"error": null,
"warnings": [],
"webhook_metadata": { "call_id": "abc-123" }
}
}

Failure:

{
"type": "speech_to_text_transcription",
"data": {
"transcription_id": "cb1594c2-d447-490a-9695-1a24be951495",
"request_id": "cb1594c2-d447-490a-9695-1a24be951495",
"status": "failed",
"transcription": null,
"error": {
"code": "processing_timeout",
"message": "Transcription did not complete: 3 of 5 audio segments were processed in time"
},
"warnings": [],
"webhook_metadata": { "call_id": "abc-123" }
}
}
FieldDescription
typeAlways speech_to_text_transcription.
data.transcription_idThe transcription_id from the 202 response.
data.request_idThe request_id from the 202 response.
data.statuscompleted or failed.
data.transcriptionThe transcript, in the same shape as the synchronous response. null when status is failed.
data.errornull on success. On failure, { "code", "message" }. Branch on code.
data.warningsNon-fatal issues on a completed job. Usually empty.
data.webhook_metadataThe webhook_metadata you sent, unchanged.

On failure, data.transcription is null. Read data.status before you read data.transcription.text.

error.codeMeaningWhat to do
processing_timeoutPart of the audio was not transcribed in time. The limit is the longer of 15 minutes and the audio length.Retry. Contact support if it repeats.
transcription_failedNone of the speech in the file could be transcribed.Retry. If it repeats for the same file, contact support with the transcription_id.
internal_errorUnexpected server error.Retry. Contact support if it repeats.

A completed job can include a warning. The transcript is returned without the segments that were dropped.

warnings[].codeMeaning
partial_audio_droppedSome segments could not be transcribed. dropped_audio_secs is how many seconds were left out. message says how many segments.
{
"warnings": [
{
"code": "partial_audio_dropped",
"message": "1 of 12 audio segments could not be transcribed",
"dropped_audio_secs": 4.2
}
]
}

Respond with any 2xx status to acknowledge the webhook. Any other status, a timeout of 10 seconds, or a connection error is a failed delivery. Murf retries 4 times, at 1, 5, 30, and 120 seconds after each failed attempt: 5 attempts over about 2.5 minutes. The same job can be delivered more than once. Ignore duplicates by data.transcription_id or the X-Murf-Transcription-Id header.

A webhook is not guaranteed to arrive. If nothing arrives within 15 minutes plus the length of the audio, poll the job, then submit the file again.

There is no signature on the request. A hard-to-guess webhook_url is the way to keep other callers from posting to it.

Polling

Poll when you are not using a webhook, or when a webhook does not arrive. Call the same host you uploaded the file to.

curl "https://us-east.api.murf.ai/v1/transcription/speech-to-text/transcripts/{transcription_id}" \
-H "api-key: $MURF_API_KEY"
{
"transcription_id": "cb1594c2-d447-490a-9695-1a24be951495",
"status": "completed",
"result": {
"transcription_id": "cb1594c2-d447-490a-9695-1a24be951495",
"language_code": "en",
"language_probability": 1.0,
"text": "Hello from Murf.",
"words": [],
"audio_duration_secs": 5.5
},
"error": null,
"warnings": []
}
FieldDescription
statusprocessing, completed, or failed.
resultThe transcript when completed, in the same shape as the synchronous response. Otherwise null.
errorThe same object as the webhook error when failed. Otherwise null.
warningsThe same list as the webhook warnings.

Use the API key that submitted the job. A different key, including another key in the same account, returns 404. A missing key returns 401. The result is kept for 24 hours after the job finishes, and then the endpoint returns 404.

Poll every few seconds at most. For a long file, every 10 to 30 seconds is enough.

Pricing

File transcription costs $0.12 per hour of audio, billed from audio_duration_secs. Enterprise discounts apply the same way as streaming. bvc does not change the price. A failed job is not billed. A completed job is billed for the full audio length, including a job that returns warnings.

See Pricing

Next steps