POST /v1/audio/transcriptions
What it does
Transcribe a single speech clip synchronously. This endpoint is OpenAI Whisper-compatible (multipart/form-data + file).
Client responsibility: you must segment speech with your own VAD before calling. Do not send continuous silence — the service does not filter silence, empty clips, or low-energy audio. Whatever you POST is transcribed and billed.
Typical integrators: voice clients (e.g. Flow) that detect utterance boundaries locally and upload each clip as WAV.
Endpoint
POST /v1/audio/transcriptions
Authentication
Authorization: Bearer sk-...
Request
Content-Type: multipart/form-data
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| file | file | yes | — | Speech clip (WAV, MP3, etc.) |
| model | string | no | whisper-1 | Model name passed to workers |
| language | string | no | — | ISO-639-1 hint (zh, en, …) |
| prompt | string | no | — | Context prompt for STT |
| response_format | string | no | verbose_json | verbose_json, json, or text |
| worker_id | string | no | — | Pin to a specific worker ID |
::callout{icon="i-lucide-triangle-alert" color="amber"}
Not for long files or raw recordings
Use [Batch Jobs](/docs/api-reference/batch-jobs) (POST /v1/audio/transcriptions/jobs) for audio_url async processing. Use [Realtime WS](/docs/api-reference/realtime-api) when the server should run VAD on a PCM stream.
::
Example
curl -X POST https://audio.lansonai.com/v1/audio/transcriptions \
-H "Authorization: Bearer sk-..." \
-F "file=@utterance.wav" \
-F "language=zh" \
-F "response_format=verbose_json"
Response — 200 OK
verbose_json (default):
{
"text": "你好世界",
"language": "zh",
"duration": 1.2,
"segments": [],
"words": []
}
Response headers:
| Header | Description |
|---|---|
| X-Worker-Id | Worker that produced the result |
| X-Fallback-Used | 1 if a fallback worker was used, else 0 |
Latency and retries
| Rule | Value | |---|---| | Per-attempt timeout | 800 ms (Modal + ElevenLabs) | | Max POST attempts per request | 2 (primary warm Modal → ElevenLabs when applicable) | | Server HTTP retry | No — failed requests return an error; client may resend | | Cold Modal | Not POSTed on this request; health probe may run async; ElevenLabs used for cold path |
Wall-clock budget is roughly ≤1.6 s on the warm Modal + fallback path.
Errors
| Status | Code | Description |
|---|---|---|
| 400 | invalid_content_type | Body is not multipart/form-data |
| 400 | missing_file | No file field |
| 401 | — | Authentication failed |
| 502 | transcription_failed | All worker attempts failed |
{
"error": {
"message": "Realtime transcription timed out after 800ms",
"type": "invalid_request_error",
"code": "transcription_failed"
}
}