Skip to main content
POST
/
api
/
v1
/
audio
/
stt
Speech to Text
curl --request POST \
  --url https://api.example.com/api/v1/audio/stt \
  --header 'Content-Type: application/json' \
  --data '
{
  "file": {},
  "language": "<string>"
}
'
{
  "id": "<string>",
  "created": "<string>",
  "text": "<string>",
  "language": {},
  "duration_seconds": {},
  "usage": {
    "cost_cents": 123
  }
}
Transcribe an audio file to text. Uses multipart form upload (not JSON). Maximum file size: 25 MB.

​
Authentication

Requires a Bearer token. See Authentication.

​
Request Body (multipart/form-data)

​
file
Blob
required
Audio file to transcribe. Supported formats: MP3, MP4, MPEG, MPGA, M4A, WAV, WEBM.
​
language
string
Language hint (ISO 639-1 code, e.g., "en", "es", "fr"). If omitted, language is auto-detected.

​
Request Examples

curl -X POST https://hitheo.ai/api/v1/audio/stt \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -F "file=@recording.mp3" \
  -F "language=en"

​
Response

​
id
string
Unique transcription ID (prefixed stt_).
​
created
string
ISO 8601 timestamp.
​
text
string
The transcribed text.
​
language
string | null
Detected or specified language.
​
duration_seconds
number | null
Duration of the audio file in seconds.
​
usage
object

​
Example Response

{
  "id": "stt_abc123",
  "created": "2026-04-10T12:00:00Z",
  "text": "Welcome to Theo. How can I help you today?",
  "language": "en",
  "duration_seconds": 3.2,
  "usage": { "cost_cents": 0.01 }
}

​
Errors

StatusCodeDescription
400missing_filefile is required (multipart form upload)
401invalid_api_keyMissing or invalid API key
502stt_provider_errorTheo transcription engine returned an error — retry
503stt_unavailableSTT is not configured on this instance