> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://murf.ai/api/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://murf.ai/api/docs/_mcp/server.

# File transcription

> Transcribe a recorded audio file with Finch-Indic or Finch-Global. Upload the file over HTTPS and receive one transcript, with word timestamps, by waiting, webhook, or polling.

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](/api/docs/speech-to-text/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
```

| Model              | Host                  | Languages                                                                                 |
| ------------------ | --------------------- | ----------------------------------------------------------------------------------------- |
| `finch_indic_1.0`  | `in.api.murf.ai`      | Indic languages and English (India). See [Languages](/api/docs/speech-to-text/languages). |
| `finch_global_1.0` | `us-east.api.murf.ai` | English and European languages. See [Languages](/api/docs/speech-to-text/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`.

| Method            | Example                              |
| ----------------- | ------------------------------------ |
| Header (use this) | `api-key: YOUR_API_KEY`              |
| Header            | `xi-api-key: YOUR_API_KEY`           |
| Header            | `Authorization: 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`.

```bash
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"
```

| Field                    | Required              | Description                                                                                                                                                                                                                             |
| ------------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file`                   | Yes                   | The audio file. See [Audio formats](#audio-formats). A request without this field returns `422` before the API key is checked.                                                                                                          |
| `model`                  | Yes                   | `finch_indic_1.0` or `finch_global_1.0`. You can send `model_id` instead.                                                                                                                                                               |
| `language_code`          | No                    | A language tag from [Languages](/api/docs/speech-to-text/languages), such as `hi` or `en_IN`. Omit it, or send `auto`, to detect the language.                                                                                          |
| `keyterms`               | No                    | A phrase to boost. Repeat the field once per phrase. There is no strength setting. See [Keyword boosting](/api/docs/speech-to-text/keyword-boosting).                                                                                   |
| `timestamps_granularity` | No                    | `word` (default) or `none`. `none` omits `words`.                                                                                                                                                                                       |
| `bvc`                    | No                    | `true` 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_retention`         | No                    | Workspace 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.                                                                                           |
| `webhook`                | No                    | `true` returns `202` immediately and delivers the result to `webhook_url`. Beta.                                                                                                                                                        |
| `webhook_url`            | When `webhook` is set | Where Murf POSTs the result. Use a hard-to-guess URL. Webhooks are not signed.                                                                                                                                                          |
| `webhook_metadata`       | No                    | A 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               |                                     |
| -------------------- | ----------------------------------- |
| WAV                  | Supported                           |
| FLAC                 | Supported                           |
| OGG (Vorbis or Opus) | Supported                           |
| M4A, AAC, MP4, WebM  | `400` `Unable to decode audio file` |

## Limits

| Limit                      | Value                 | Response                                       |
| -------------------------- | --------------------- | ---------------------------------------------- |
| Upload size                | 1 GB                  | `413`                                          |
| Audio length               | 3600 seconds (1 hour) | `400`, audio longer than 3600 seconds          |
| Jobs running on one server | 8                     | `429` `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](/api/docs/resources/rate-limits) and [Errors](/api/docs/speech-to-text/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.

```json
{
  "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:

```json
{
  "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.

```json
{ "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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" }
  }
}
```

| Field                   | Description                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| `type`                  | Always `speech_to_text_transcription`.                                                           |
| `data.transcription_id` | The `transcription_id` from the `202` response.                                                  |
| `data.request_id`       | The `request_id` from the `202` response.                                                        |
| `data.status`           | `completed` or `failed`.                                                                         |
| `data.transcription`    | The transcript, in the same shape as the synchronous response. `null` when `status` is `failed`. |
| `data.error`            | `null` on success. On failure, `{ "code", "message" }`. Branch on `code`.                        |
| `data.warnings`         | Non-fatal issues on a completed job. Usually empty.                                              |
| `data.webhook_metadata` | The `webhook_metadata` you sent, unchanged.                                                      |

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

| `error.code`           | Meaning                                                                                                    | What to do                                                                           |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `processing_timeout`   | Part 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_failed` | None of the speech in the file could be transcribed.                                                       | Retry. If it repeats for the same file, contact support with the `transcription_id`. |
| `internal_error`       | Unexpected 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[].code`       | Meaning                                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `partial_audio_dropped` | Some segments could not be transcribed. `dropped_audio_secs` is how many seconds were left out. `message` says how many segments. |

```json
{
  "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.

```bash
curl "https://us-east.api.murf.ai/v1/transcription/speech-to-text/transcripts/{transcription_id}" \
  -H "api-key: $MURF_API_KEY"
```

```json
{
  "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": []
}
```

| Field      | Description                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------- |
| `status`   | `processing`, `completed`, or `failed`.                                                           |
| `result`   | The transcript when `completed`, in the same shape as the synchronous response. Otherwise `null`. |
| `error`    | The same object as the webhook `error` when `failed`. Otherwise `null`.                           |
| `warnings` | The 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](https://murf.ai/pricing?product=api)

## Next steps

#### [Streaming](/api/docs/speech-to-text/streaming)

Transcribe live audio over a WebSocket.

#### [Errors](/api/docs/speech-to-text/errors)

WebSocket close codes, then the HTTP statuses for file transcription.

#### [Languages](/api/docs/speech-to-text/languages)

Language tags for `language_code`.

#### [API reference](/api/docs/api-reference/speech-to-text/file)

The upload and polling operations.