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.
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.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
input.file_url | string | One of two | An HTTPS audio URL accessible without additional request headers. Use either this field or input.upload_id. |
input.upload_id | string | One of two | The identifier returned by the upload API. Use either this field or input.file_url. |
model | string | No | Optional model identifier; defaults to the value shown. stt-async-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. |
webhook_id | string | No | An endpoint registered with POST /v1/webhooks. |
2. Check job status
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.
| Field | Description |
|---|---|
status | accepted, processing, succeeded, failed, or cancelled. |
result_expires_at | Result expiration time in ISO 8601, or null before a result is available. |
3. Read the result
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.
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.
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.
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.
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.
| 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. |