[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"article-doc:docs\u002Fapi-reference\u002Fsegment-transcription":3},"---\ntitle: Segment Transcription API\ndescription: Synchronous client-VAD speech segment transcription (multipart).\n---\n\n## POST \u002Fv1\u002Faudio\u002Ftranscriptions\n\n### What it does\n\nTranscribe a **single speech clip** synchronously. This endpoint is OpenAI Whisper-compatible (`multipart\u002Fform-data` + `file`).\n\n**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.\n\nTypical integrators: voice clients (e.g. Flow) that detect utterance boundaries locally and upload each clip as WAV.\n\n### Endpoint\n\n```\nPOST \u002Fv1\u002Faudio\u002Ftranscriptions\n```\n\n### Authentication\n\n```\nAuthorization: Bearer sk-...\n```\n\n### Request\n\n`Content-Type: multipart\u002Fform-data`\n\n| Field | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `file` | file | **yes** | — | Speech clip (WAV, MP3, etc.) |\n| `model` | string | no | `whisper-1` | Model name passed to workers |\n| `language` | string | no | — | ISO-639-1 hint (`zh`, `en`, …) |\n| `prompt` | string | no | — | Context prompt for STT |\n| `response_format` | string | no | `verbose_json` | `verbose_json`, `json`, or `text` |\n| `worker_id` | string | no | — | Pin to a specific worker ID |\n\n::callout{icon=\"i-lucide-triangle-alert\" color=\"amber\"}\nNot for long files or raw recordings\nUse [Batch Jobs](\u002Fdocs\u002Fapi-reference\u002Fbatch-jobs) (`POST \u002Fv1\u002Faudio\u002Ftranscriptions\u002Fjobs`) for `audio_url` async processing. Use [Realtime WS](\u002Fdocs\u002Fapi-reference\u002Frealtime-api) when the server should run VAD on a PCM stream.\n::\n\n### Example\n\n```bash\ncurl -X POST https:\u002F\u002Faudio.lansonai.com\u002Fv1\u002Faudio\u002Ftranscriptions \\\n  -H \"Authorization: Bearer sk-...\" \\\n  -F \"file=@utterance.wav\" \\\n  -F \"language=zh\" \\\n  -F \"response_format=verbose_json\"\n```\n\n### Response — 200 OK\n\n`verbose_json` (default):\n\n```json\n{\n  \"text\": \"你好世界\",\n  \"language\": \"zh\",\n  \"duration\": 1.2,\n  \"segments\": [],\n  \"words\": []\n}\n```\n\nResponse headers:\n\n| Header | Description |\n|---|---|\n| `X-Worker-Id` | Worker that produced the result |\n| `X-Fallback-Used` | `1` if a fallback worker was used, else `0` |\n\n### Latency and retries\n\n| Rule | Value |\n|---|---|\n| Per-attempt timeout | 800 ms (Modal + ElevenLabs) |\n| Max POST attempts per request | 2 (primary warm Modal → ElevenLabs when applicable) |\n| Server HTTP retry | **No** — failed requests return an error; client may resend |\n| Cold Modal | Not POSTed on this request; health probe may run async; ElevenLabs used for cold path |\n\nWall-clock budget is roughly **≤1.6 s** on the warm Modal + fallback path.\n\n### Errors\n\n| Status | Code | Description |\n|---|---|---|\n| 400 | `invalid_content_type` | Body is not `multipart\u002Fform-data` |\n| 400 | `missing_file` | No `file` field |\n| 401 | — | Authentication failed |\n| 502 | `transcription_failed` | All worker attempts failed |\n\n```json\n{\n  \"error\": {\n    \"message\": \"Realtime transcription timed out after 800ms\",\n    \"type\": \"invalid_request_error\",\n    \"code\": \"transcription_failed\"\n  }\n}\n```\n\n## Related\n\n- [Client-VAD segments guide](\u002Fdocs\u002Fguides\u002Fclient-vad-segments)\n- [Batch Jobs](\u002Fdocs\u002Fapi-reference\u002Fbatch-jobs)\n- [Choose an API](\u002Fdocs\u002Fstart\u002Fchoose-an-api)\n- [Errors](\u002Fdocs\u002Fapi-reference\u002Ferrors)\n",1790059118947]