Browse documentation

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.

bash
curl "https://api.lecsync.com/v1/audio/transcriptions" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: transcription-example-001" \  -F "file=@recording.wav" \  -F "language=en" \  -F "timestamps=none" \  -F "diarization=false" \  -F 'hotwords=["LecSync"]'

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.

FieldTypeRequiredDescription
filefileYesAudio file.
modelstringNoOptional model identifier; defaults to the value shown. stt-sync-default.
languagestringNoAudio language code, such as en or zh; defaults to auto.
timestampsstringNonone (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.
diarizationbooleanNoSet to true to include speaker labels; defaults to false.
hotwordsstring[]NoUp 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.

json
{  "request_id": "req_example",  "status": "succeeded",  "model": "stt-sync-default",  "text": "Hello world.",  "language": "en"}
FieldDescription
request_idRequest identifier. Save it for status queries and troubleshooting.
statusaccepted, processing, succeeded, failed, or cancelled.
textFull transcript.
languageRecognized language, or null when unavailable.
segmentsSegments containing text, start_ms, and end_ms.
wordsWords containing text, start_ms, and end_ms; returned for timestamps=word.
result_expires_atResult 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.

bash
curl "https://api.lecsync.com/v1/requests/REQUEST_ID" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

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.

json
{  "error": "INVALID_INPUT",  "request_id": "req_example"}
HTTPerrorHandling
401UNAUTHORIZEDCheck the API key.
402INSUFFICIENT_BALANCECheck your API balance before retrying.
503ADMISSION_DISABLEDThe requested service is not available for this account.
409IDEMPOTENCY_CONFLICTQuery the existing request, or use a new key for different input.
410RESULT_EXPIREDThe result is no longer available; submit a new request if needed.
413BODY_TOO_LARGE / AUDIO_TOO_LONGReduce the file size or duration.
415UNSUPPORTED_AUDIO_FORMATConvert the file to a supported format.
422INVALID_INPUT / INVALID_IDEMPOTENCY_KEY / PARAMETER_CONFLICT / CAPABILITY_UNAVAILABLECheck field names, types, and required values.
422UNSUPPORTED_LANGUAGECheck field names, types, and required values.
429RESOURCE_LIMITWait for Retry-After before retrying.
503MODEL_UNAVAILABLE / SERVICE_UNAVAILABLECheck the existing request status before retrying.
504DEADLINE_EXCEEDEDQuery the request status before starting another request.