File transcription
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.
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.
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.
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.
Limits
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.
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:
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.
Webhook
Beta. Set webhook=true and webhook_url. The upload returns 202 immediately:
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:
Failure:
On failure, data.transcription is null. Read data.status before you read data.transcription.text.
A completed job can include a warning. The transcript is returned without the segments that were dropped.
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.
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.