Browse documentation

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

bash
curl "https://api.lecsync.com/v1/translate" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: translation-example-001" \  -H "Content-Type: application/json" \  -d '{  "text": "Hello world.",  "source_lang": "en",  "target_lang": "zh",  "context": "A welcome message.",  "terms": [    {      "source": "world",      "target": "世界"    }  ]}'

Parameters

FieldTypeRequiredDescription
textstringYesA non-empty text string, at most 2,000 Unicode characters.
target_langstringYesTarget language code, such as zh, en, or ja.
source_langstringNoSource language; defaults to auto. Specify it for short or ambiguous text.
contextstringNoBackground context, at most 2,000 Unicode characters.
termsobject[]NoUp to 20 {source, target} terminology pairs; each side at most 120 Unicode characters.
modelstringNoOptional model identifier; defaults to the value shown. translate-default.

Response

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

json
{  "request_id": "req_example",  "status": "succeeded",  "text": "你好,世界。",  "source_lang": "en",  "target_lang": "zh",  "model": "translate-default",  "unchanged": false}
FieldDescription
request_idRequest identifier. Save it for status queries and troubleshooting.
statusaccepted, processing, succeeded, failed, or cancelled.
textTranslated text.
source_langSource language; defaults to auto. Specify it for short or ambiguous text.
target_langTarget language code, such as zh, en, or ja.
unchangedtrue when source and target languages are the same; text is returned unchanged.
result_expires_atResult 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.

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

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.

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.
422INVALID_INPUT / INVALID_IDEMPOTENCY_KEY / PARAMETER_CONFLICT / CAPABILITY_UNAVAILABLECheck field names, types, and required values.
422UNSUPPORTED_LANGUAGE / LANGUAGE_UNDETERMINEDUse a supported language; specify source_lang if auto-detection fails.
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.