Synchronous transcription API
Upload a short audio file and receive its transcript in the same HTTP response.
Use an API key from the API console in the Authorization: Bearer <API_KEY> header. Set LECSYNC_API_KEY in your server environment before running these examples. Keep the key on your server.
Make a request
POST /v1/audio/transcriptions
Accepted files: AAC (ADTS), MP3, Ogg Opus, WAV, and MP4 with an audio track.
Parameters
Send multipart/form-data. Let your HTTP client set the boundary. Encode hotwords and terms as JSON strings in form fields; boolean fields use true or false.
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | Audio file. |
model | string | No | Optional model identifier; defaults to the value shown. stt-sync-default. |
language | string | No | Audio language code, such as en or zh; defaults to auto. |
timestamps | string | No | none (default), segment, or word. word returns both word and segment timestamps. GPU transcription supports only none with diarization=false; other combinations require the operator to enable Soniox fallback, otherwise the request fails with CAPABILITY_UNAVAILABLE. |
diarization | boolean | No | Set to true to include speaker labels; defaults to false. |
hotwords | string[] | No | Up to 50 recognition hints, each at most 120 Unicode characters. |
Response
The examples below show the main response fields; additional usage metadata may be present.
| Field | Description |
|---|---|
request_id | Request identifier. Save it for status queries and troubleshooting. |
status | accepted, processing, succeeded, failed, or cancelled. |
text | Full transcript. |
language | Recognized language, or null when unavailable. |
segments | Segments containing text, start_ms, and end_ms. |
words | Words containing text, start_ms, and end_ms; returned for timestamps=word. |
result_expires_at | Result expiration time in ISO 8601, or null before a result is available. |
Timestamps are milliseconds from the beginning of the recording. When diarization is enabled, timestamp entries can include speaker. Word entries exclude standalone punctuation; the transcript retains punctuation.
Retrieve results and retry
Send an Idempotency-Key of 1–128 visible ASCII characters with each new execution request. Save the key and reuse it with identical input if the response is lost. Different input with the same key returns 409 IDEMPOTENCY_CONFLICT. A request already in progress returns its status without running again. A new key starts a new request.
Successful results are retained for 24 hours by default. Query GET /v1/requests/{request_id} to retrieve them: the stored payload is under result. A successful POST retry also uses this wrapper. After expiry, the endpoint returns 410 RESULT_EXPIRED. Use result_expires_at as the authoritative expiry time.
Limits and usage
- Maximum file size: 20 MiB
- Maximum audio duration: 120 s
Transcription is charged by the actual audio duration, without rounding up to whole minutes.
usage.charge_cents is the charged amount as a decimal string in US cents.
Use GET /v1/models to check currently available models, languages, limits, prices, and result retention.
Errors
HTTP errors return error and request_id; the response header also includes X-Request-Id. Preserve the identifier when reporting a problem.
| HTTP | error | Handling |
|---|---|---|
| 401 | UNAUTHORIZED | Check the API key. |
| 402 | INSUFFICIENT_BALANCE | Check your API balance before retrying. |
| 503 | ADMISSION_DISABLED | The requested service is not available for this account. |
| 409 | IDEMPOTENCY_CONFLICT | Query the existing request, or use a new key for different input. |
| 410 | RESULT_EXPIRED | The result is no longer available; submit a new request if needed. |
| 413 | BODY_TOO_LARGE / AUDIO_TOO_LONG | Reduce the file size or duration. |
| 415 | UNSUPPORTED_AUDIO_FORMAT | Convert the file to a supported format. |
| 422 | INVALID_INPUT / INVALID_IDEMPOTENCY_KEY / PARAMETER_CONFLICT / CAPABILITY_UNAVAILABLE | Check field names, types, and required values. |
| 422 | UNSUPPORTED_LANGUAGE | Check field names, types, and required values. |
| 429 | RESOURCE_LIMIT | Wait for Retry-After before retrying. |
| 503 | MODEL_UNAVAILABLE / SERVICE_UNAVAILABLE | Check the existing request status before retrying. |
| 504 | DEADLINE_EXCEEDED | Query the request status before starting another request. |