Browse documentation

Voice Typing API

Speak to type: turn a short recording into text for input fields, messages, and documents.

Build voice input for editors, chat boxes, forms, and keyboard tools. Send a short utterance over HTTP or WebSocket and insert the returned text into the active input in your application. The API generates the text; your client handles insertion. Voice typing only converts speech to text and returns the recognition result as is; it does not polish, replace words or translate. WebSocket results arrive after end, without partial captions.

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/voicetyping

Accepted files: AAC (ADTS), MP3, Ogg Opus, and WAV. MP4 and video files are not supported.

bash
curl "https://api.lecsync.com/v1/voicetyping" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: voicetyping-example-001" \  -F "file=@recording.wav" \  -F "language=en" \  -F 'terms=["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.
languagestringNoAudio language code, such as en or zh; defaults to auto.
termsarrayNoUp to 50 hotwords (strings, at most 120 characters each) that improve recognition of names and terms.

Response

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

json
{  "request_id": "req_example",  "status": "succeeded",  "text": "hello world",  "language": "en"}
FieldDescription
request_idRequest identifier. Save it for status queries and troubleshooting.
textRecognized text.
languageRecognized language, or null when unavailable.

WebSocket input

Create a connection from your server using the same JSON parameters as HTTP, without file. The response supplies websocket_url, protocol, ticket, expires_at, and limits. Connect before the ticket expires (60 seconds); each ticket can be used once.

bash
curl "https://api.lecsync.com/v1/voicetyping/connect" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: voicetyping-ws-example-001" \  -H "Content-Type: application/json" \  -d '{  "language": "en",  "terms": [    "LecSync"  ]}'

Open the socket with subprotocols [protocol, ticket]. Wait for ready, then send binary 16 kHz mono PCM16 little-endian audio, without a WAV header. Each frame must be non-empty, have an even byte length, and contain at most 65,536 bytes. Send {"type":"end"} after the last frame and wait for result or error. Results arrive once the utterance is complete; there are no partial captions. The idle timeout is 60 seconds.

javascript
const ws = new WebSocket(connection.websocket_url, [  connection.protocol,  connection.ticket,]);ws.onmessage = ({ data }) => {  const message = JSON.parse(data);  if (message.type === "ready") {    // pcmFrames: 16 kHz mono PCM16 ArrayBuffer[]    for (const frame of pcmFrames) ws.send(frame);    ws.send(JSON.stringify({ type: "end" }));  } else if (message.type === "result") {    console.log(message.text);  } else if (message.type === "error") {    console.error(message.error);  }};

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.

Save text when it arrives. Voice typing text cannot be retrieved again: GET /v1/voicetyping/requests/{request_id} and repeated requests return status and usage metadata only (result_replay_supported=false).

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

Limits and usage

  • Maximum file size: 20 MiB
  • Maximum audio duration: 120 s

Voice typing is charged by the final text character count, excluding whitespace.

usage.charge_cents is the charged amount as a decimal string in US cents.

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.