Browse documentation

Asynchronous transcription API

Submit a recording, track its progress, and retrieve the transcript in pages.

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.

1. Submit a recording

Accepted files: AAC (ADTS), MP3, Ogg Opus, WAV, and MP4 with an audio track.

bash
curl "https://api.lecsync.com/v1/audio/transcription-jobs" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: job-example-001" \  -H "Content-Type: application/json" \  -d '{  "input": {    "file_url": "https://example.com/recording.mp3"  },  "language": "en",  "timestamps": "none",  "diarization": false}'

Creation returns HTTP 202 with job_id. This means the job was accepted; transcription is still pending.

The examples below show the main response fields; additional usage metadata may be present.

json
{  "job_id": "req_example",  "request_id": "req_example",  "status": "accepted",  "progress": 0,  "result_url": "/v1/audio/transcription-jobs/req_example/result"}

Parameters

FieldTypeRequiredDescription
input.file_urlstringOne of twoAn HTTPS audio URL accessible without additional request headers. Use either this field or input.upload_id.
input.upload_idstringOne of twoThe identifier returned by the upload API. Use either this field or input.file_url.
modelstringNoOptional model identifier; defaults to the value shown. stt-async-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.
webhook_idstringNoAn endpoint registered with POST /v1/webhooks.

2. Check job status

bash
curl "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

Poll the status endpoint at a reasonable interval, for example every 3 seconds. Continue while status is accepted or processing; read results after succeeded. For failed or cancelled, inspect error and stop polling. progress is an estimate from 0 to 100.

FieldDescription
statusaccepted, processing, succeeded, failed, or cancelled.
result_expires_atResult expiration time in ISO 8601, or null before a result is available.

3. Read the result

bash
curl "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID/result?cursor=0" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

Start at cursor=0 and follow next_cursor until it is null. Append each page’s result.text in order, and concatenate its words and segments arrays separately. Text slices and timestamp arrays are paginated independently. Reading before completion returns 409 RESULT_NOT_READY.

json
{  "job_id": "req_example",  "request_id": "req_example",  "language": "en",  "result": {    "text": "Hello world."  },  "cursor": 0,  "next_cursor": null,  "page_count": 1}

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.

Results are retained for 7 days by default; check result_expires_at. Expired results return 410 RESULT_EXPIRED.

Upload a local file

For a local file, request an upload URL with its exact byte size and lowercase hexadecimal SHA-256. The response contains upload_id, upload_url, headers, and expires_at. PUT the file to upload_url using every returned header, then submit input.upload_id within 15 minutes. Do not send your API key to the upload URL. The complete example below uses curl, jq, and shasum.

bash
FILE=recording.wavSIZE=$(wc -c < "$FILE" | tr -d ' ')SHA256=$(shasum -a 256 "$FILE" | cut -d ' ' -f 1)UPLOAD=$(curl --fail-with-body "https://api.lecsync.com/v1/audio/uploads" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: upload-example-001" \  -H "Content-Type: application/json" \  -d "{\"size_bytes\":$SIZE,\"sha256\":\"$SHA256\"}")
curl --fail-with-body -X PUT "$(printf '%s' "$UPLOAD" | jq -r '.upload_url')" \  -H "Content-Type: $(printf '%s' "$UPLOAD" | jq -r '.headers["content-type"]')" \  -H "Content-Length: $(printf '%s' "$UPLOAD" | jq -r '.headers["content-length"]')" \  -H "x-amz-checksum-sha256: $(printf '%s' "$UPLOAD" | jq -r '.headers["x-amz-checksum-sha256"]')" \  --data-binary "@$FILE"
UPLOAD_ID=$(printf '%s' "$UPLOAD" | jq -r '.upload_id')curl "https://api.lecsync.com/v1/audio/transcription-jobs" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: uploaded-job-example-001" \  -H "Content-Type: application/json" \  -d "{\"input\":{\"upload_id\":\"$UPLOAD_ID\"},\"timestamps\":\"none\"}"

Cancel or delete a job

POST /v1/audio/transcription-jobs/{job_id}/cancel requests cancellation. Continue checking status until the job reaches a terminal state; any refund is completed after processing stops. DELETE /v1/audio/transcription-jobs/{job_id} removes access to the result immediately. Deleted jobs return 404.

bash
curl -X POST "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID/cancel" \  -H "Authorization: Bearer $LECSYNC_API_KEY"
curl -X DELETE "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

Completion webhooks

Register a public HTTPS endpoint, keep the returned secret, and include webhook_id when creating a job. Events are transcription.succeeded, transcription.failed, or transcription.cancelled; they contain job_id, status, and result_url, without the transcript.

bash
curl "https://api.lecsync.com/v1/webhooks" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: webhook-example-001" \  -H "Content-Type: application/json" \  -d '{  "url": "https://example.com/webhooks/transcription"}'

Verify LecSync-Signature as v1=<hex> using HMAC-SHA256 over LecSync-Timestamp + "." + raw request body. Reject timestamps more than 5 minutes from the current time and deduplicate by LecSync-Event-Id. Use LecSync-Secret-Version to select the secret after rotation. Respond with 2xx after accepting an event. Network errors, 429, and 5xx are retried for up to 24 hours; other 4xx responses stop delivery.

Use GET /v1/webhooks/{id}/deliveries to inspect delivery status, POST /v1/webhooks/deliveries/{id}/resend to resend, and POST /v1/webhooks/{id}/rotate-secret to rotate the secret. Rotation and resend require their own Idempotency-Key.

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.

Limits and usage

  • Maximum file size: 200 MiB
  • Maximum audio duration: 7200 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.