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

# Transcribe Audio

> Convert a recorded audio clip to text with one-shot speech-to-text

Upload a complete recorded audio clip and receive the final transcript in a single round-trip. Use this to power voice input in your app: record the clip, upload it, and place the returned text in your chat composer.

This endpoint complements [Create Voice Session](/api-reference/voice/create-session): voice sessions provide real-time conversational audio, while this endpoint transcribes a finished recording. There is no streaming upload and no progressive results — the response contains the final corrected text, returned once.

<Note>
  Transcripts are post-processed with a vocabulary-biasing step tuned for project and place names (e.g., "Saadiyat", "Yas"), so proper nouns come back spelled consistently.
</Note>

This endpoint is rate-limited to **20 requests per minute per JWT**. Excess requests return `429` with a `Retry-After` header.

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from the authenticate endpoint.
</ParamField>

<ParamField body="file" type="file" required>
  The recorded audio clip, sent as `multipart/form-data`. Maximum 25 MB; keep clips under \~10 minutes.

  Accepted MIME types:

  * `audio/m4a`
  * `audio/x-m4a`
  * `audio/mp4`

  Recommended encoding: AAC in an `.m4a` container, 16 kHz, mono, \~32 kbps. Other formats (WAV, WebM, MP3) are rejected with `400`.
</ParamField>

## Response

<ResponseField name="text" type="string" required>
  The final transcript, after speech-to-text and proper-noun correction.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.trellis.sh/v1/audio/transcribe \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -F "file=@recording.m4a;type=audio/m4a"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  with open("recording.m4a", "rb") as audio:
      response = requests.post(
          "https://api.trellis.sh/v1/audio/transcribe",
          headers={"Authorization": "Bearer YOUR_TOKEN"},
          files={"file": ("recording.m4a", audio, "audio/m4a")},
      )
  text = response.json()["text"]
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const form = new FormData();
  form.append("file", audioBlob, "recording.m4a");

  const response = await fetch("https://api.trellis.sh/v1/audio/transcribe", {
    method: "POST",
    headers: { Authorization: "Bearer YOUR_TOKEN" },
    body: form,
  });
  const { text } = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "text": "What is the handover status for Saadiyat Lagoons?"
  }
  ```

  ```json 400 Unsupported format theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "Unsupported audio format: audio/wav. Accepted: audio/m4a, audio/x-m4a, audio/mp4 (AAC in .m4a container; 16 kHz mono ~32 kbps recommended)."
  }
  ```

  ```json 400 File too large theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "File too large. Maximum size is 25MB, got 31.4MB"
  }
  ```

  ```json 400 Empty file theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "Empty audio file"
  }
  ```

  ```json 401 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "Invalid or expired token"
  }
  ```

  ```json 429 Rate limited theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "code": "RATE_LIMIT",
    "retry_after_seconds": 12
  }
  ```

  ```json 500 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "Failed to transcribe audio"
  }
  ```
</ResponseExample>