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.
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. |
language | string | No | Audio language code, such as en or zh; defaults to auto. |
terms | array | No | Up 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.
| Field | Description |
|---|---|
request_id | Request identifier. Save it for status queries and troubleshooting. |
text | Recognized text. |
language | Recognized 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.
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.
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).
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.
| 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. |