Text translation API
Translate a text string into a target language, with optional context and terminology.
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/translate
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
text | string | Yes | A non-empty text string, at most 2,000 Unicode characters. |
target_lang | string | Yes | Target language code, such as zh, en, or ja. |
source_lang | string | No | Source language; defaults to auto. Specify it for short or ambiguous text. |
context | string | No | Background context, at most 2,000 Unicode characters. |
terms | object[] | No | Up to 20 {source, target} terminology pairs; each side at most 120 Unicode characters. |
model | string | No | Optional model identifier; defaults to the value shown. translate-default. |
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. |
status | accepted, processing, succeeded, failed, or cancelled. |
text | Translated text. |
source_lang | Source language; defaults to auto. Specify it for short or ambiguous text. |
target_lang | Target language code, such as zh, en, or ja. |
unchanged | true when source and target languages are the same; text is returned unchanged. |
result_expires_at | Result expiration time in ISO 8601, or null before a result is available. |
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.
Limits and usage
Translation is charged by the source text character count. Context and terminology are not included. Same-language requests are metered normally.
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. |
| 422 | INVALID_INPUT / INVALID_IDEMPOTENCY_KEY / PARAMETER_CONFLICT / CAPABILITY_UNAVAILABLE | Check field names, types, and required values. |
| 422 | UNSUPPORTED_LANGUAGE / LANGUAGE_UNDETERMINED | Use a supported language; specify source_lang if auto-detection fails. |
| 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. |