POST /v1/audio/transcriptions
What it does
Use the Segment path of Lanson Live API to transcribe a single speech clip synchronously. This endpoint accepts OpenAI-compatible multipart/form-data requests with a 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.
Billing: this endpoint is metered by processed audio and billed at the offline transcription rate. See API pricing.
Endpoint
POST /v1/audio/transcriptionsAuthentication
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 | — | Optional compatibility field; omit it. Clients that require a name can use lanson-live-1. It does not select an upstream model. |
language | string | yes | — | Explicit ISO-639-1 code (zh, en, …). auto is rejected. |
prompt | string | no | — | Recognition context hint |
response_format | string | no | verbose_json | verbose_json, json, or text |
worker_id | string | no | — | Pin to a specific worker ID |
Not for long files or raw recordings
Use Batch Jobs (POST /v1/audio/transcriptions/jobs) for audio_url async processing. Use Realtime WS 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 |
| Max POST attempts per request | 3 (attempt chain: pinned → preference chain → ultimate fallback) |
| Server HTTP retry | No — failed requests return an error; client may resend |
| Cold workers | Not POSTed on this request; health probe may run async; cloud fallback used for cold path |
Wall-clock budget is ≤2.4 s (3 attempts × 800 ms).
Errors
| Status | Code | Description |
|---|---|---|
| 400 | invalid_content_type | Body is not multipart/form-data |
| 400 | missing_file | No file field |
| 400 | invalid_language | Missing language, or language=auto |
| 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"
}
}