Skip to main content
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: 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.
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.
This endpoint is rate-limited to 20 requests per minute per JWT. Excess requests return 429 with a Retry-After header.
​
Authorization
string
required
Bearer token obtained from the authenticate endpoint.
​
file
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.

​
Response

​
text
string
required
The final transcript, after speech-to-text and proper-noun correction.
curl -X POST https://api.trellis.sh/v1/audio/transcribe \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@recording.m4a;type=audio/m4a"

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"]

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();

{
  "text": "What is the handover status for Saadiyat Lagoons?"
}

{
  "detail": "Unsupported audio format: audio/wav. Accepted: audio/m4a, audio/x-m4a, audio/mp4 (AAC in .m4a container; 16 kHz mono ~32 kbps recommended)."
}

{
  "detail": "File too large. Maximum size is 25MB, got 31.4MB"
}

{
  "detail": "Empty audio file"
}

{
  "detail": "Invalid or expired token"
}

{
  "code": "RATE_LIMIT",
  "retry_after_seconds": 12
}

{
  "detail": "Failed to transcribe audio"
}