> ## Documentation Index
> Fetch the complete documentation index at: https://docs.typelessapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transcribe audio

> Submit a pre-recorded audio file and receive a refined transcript with usage metadata.

Transcribe a single pre-recorded audio file. Request body is `multipart/form-data`.

## Request

<ParamField body="audio" type="file" required>
  Audio file to transcribe. Supported formats: `wav`, `ogg`, `webm`. Max size 50 MB; max duration 300 seconds (default).
</ParamField>

<ParamField body="model" type="string" required>
  Model tier. One of `typeless-1.0-lite`, `typeless-1.0-pro`, `typeless-1.0-max`. See [Models & Pricing](/models-pricing).
</ParamField>

<ParamField body="language" type="string">
  Optional ISO 639-1 language hint (for example `en`, `zh`). When omitted — or when an unsupported/unrecognized code is supplied — the language is detected automatically and reported in `detected_language`.
</ParamField>

## Response

<ResponseField name="status" type="string">
  `"success"` on success.
</ResponseField>

<ResponseField name="result" type="object">
  <Expandable title="result fields">
    <ResponseField name="transcript" type="string">
      The refined transcript.
    </ResponseField>

    <ResponseField name="detected_language" type="string | null">
      ISO 639-1 language code detected in the audio, or `null` if detection was inconclusive.
    </ResponseField>

    <ResponseField name="duration_seconds" type="number">
      Actual duration of the audio file in seconds.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  <Expandable title="usage fields">
    <ResponseField name="billed_audio_seconds" type="number">
      Audio duration billed for this request (not the raw audio length); 15-second minimum applies.
    </ResponseField>

    <ResponseField name="output_token_count" type="integer">
      Number of tokens in the refined transcript output.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="request_id" type="string">
  26-character ULID for support.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.typelessapi.com/v1/transcribe \
    -H "Authorization: Token $TYPELESS_API_KEY" \
    -F "audio=@meeting.wav" \
    -F "model=typeless-1.0-pro"
  ```

  ```python Python theme={null}
  import os
  import requests

  with open("meeting.wav", "rb") as f:
      resp = requests.post(
          "https://api.typelessapi.com/v1/transcribe",
          headers={"Authorization": f"Token {os.environ['TYPELESS_API_KEY']}"},
          files={"audio": f},
          data={"model": "typeless-1.0-pro"},
      )
  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  import fs from "node:fs";

  const form = new FormData();
  form.append("audio", new Blob([fs.readFileSync("meeting.wav")]), "meeting.wav");
  form.append("model", "typeless-1.0-pro");

  const resp = await fetch("https://api.typelessapi.com/v1/transcribe", {
    method: "POST",
    headers: { Authorization: `Token ${process.env.TYPELESS_API_KEY}` },
    body: form,
  });
  console.log(await resp.json());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "status": "success",
  "result": {
    "transcript": "Let's move the launch to next Thursday and loop in the design team early.",
    "detected_language": "en",
    "duration_seconds": 42.5
  },
  "usage": {
    "billed_audio_seconds": 42.5,
    "output_token_count": 128
  },
  "request_id": "01JXXXXXXXXXXXXXXXXXXXXXXX"
}
```

## Endpoint-specific errors

| HTTP status | Error code                 | Description                                                                 |
| ----------- | -------------------------- | --------------------------------------------------------------------------- |
| 400         | `INVALID_REQUEST`          | `model` field is missing or the value is not a recognized model identifier. |
| 400         | `AUDIO_FORMAT_UNSUPPORTED` | The uploaded file is not in a supported format (`wav`, `ogg`, `webm`).      |
| 413         | `AUDIO_TOO_LONG`           | Audio duration exceeds the 300-second limit.                                |
| 413         | `FILE_TOO_LARGE`           | File size exceeds the 50 MB limit.                                          |

```json 400 theme={null}
{
  "status": "error",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "model is required"
  },
  "request_id": "01JXXXXXXXXXXXXXXXXXXXXXXX"
}
```

For the full list of error codes and handling guidance, see [Errors](/reference/errors).