API Quickstart

The first route

Synchronous translation involving a single logical text is natively handled by the POST /api/v1/translate endpoint. In the simplest case, only a few fields are required, including:

• request_id, a caller-provided identifier that ties a specific request to a specific response.
• tgt, the target language tag. src is optional; an empty string requests auto-detection.
• input.items, an array with exactly one item, and input.items[0].txt with the source text.

A successful translation returns a response of ok, the echoed request_id, and output.single.translation with the translated text, plus usage.input_characters, usage.output_characters, and quota state. Details on additional, optional fields are described in the translate docs.

Authentication

Calls to Lexel Translate endpoints require an API key to be authenticated. The preferred header is Authorization: Bearer lxl_... while x-api-key is also accepted for compatibility. Additional details on authentication are covered in the authentication docs. Create personal, organization, or team keys from the API keys docs. Keys can be disabled, revoked, or rotated without changing the public endpoint contract.

Language tags

Native routes use canonical language and script tags such as en-Latn, fr-Latn, and ja-Jpan, documented in the languages reference. Send canonical tags directly rather than short aliases; short aliases can be accepted for compatibility in some paths, but canonical tags give reproducible behavior. When the source language is unknown, leave src empty and read source_language_tag from the response, or run the detect endpoint first.

Structured content and placeholders

Various structured content, such as json-formatted texts, can be directly translated without worry by specifying the content_mode option, with accepted values of auto, plain, markdown, html, json, xml, yaml, and csv. No need for any preprocessing or postprocessing.

Template strings can also be automatically protected by setting preserve_placeholders. Enabling that option invokes additional processing to detect placeholder-like values and add them to protected-term handling. Setting strict_placeholder_preservation tightens enforcement by verifying whether any detected placeholder-like values could not be properly preserved. If your strings contain {name} or %s style tokens, try enabling placeholder protection for your production traffic. Besides options to preserve placeholders, do_not_translate can be used to explicitly specify protected terms such as brand names.

Glossary selection

Stored glossaries are selected per request using glossary_id. Since glossaries change over time, it may be helpful to specify glossary_version_id to pin a specific version for reproducible output. glossary_group_ids and glossary_item_ids narrow selection to specific groups or items, combined as a union. For request-scoped terminology, glossary.entries carries inline mappings and glossary.do_not_translate carries inline protected terms. Terminology control is covered in the glossaries docs; the common pattern is one stored glossary per language pair, pinned by version for production.

Error handling

Error responses come back as JSON envelopes with ok set to false and a human-readable error field, plus request_id and quota state when available. The status codes that every integration needs to handle include:

• 400 for an invalid payload or unsupported public field.
• 401 and 403 for a missing or insufficient key.
• 404 for a missing or inaccessible resource.
• 413 for a request body over the route payload limit.
• 429 for rate limit, quota, or character-limit violations.

A 429 response may include a Retry-After header with the number of seconds to wait; back off exponentially when the header is absent. API translation requires a Premium API key and Premium characters, so a request can pass rate limits and still fail quota admission. A complete list of status codes can be found in the errors and rate limits docs.

Usage and quota

Billing and client-side limits can use the usage.input_characters and usage.output_characters fields included in all successful API requests. See the usage docs for more details on how characters are counted and how usage-related endpoints can help you track consumption over time for a key, organization, or account.

Pass metadata with your own keys when you want request-level context; it is echoed in logs and responses when present, which helps route a request to the right owner during an incident.

When to add batch and async

Consider migrating from individual synchronous requests to batch requests in order to reduce networking overhead while maintaining low latency for high-concurrency workloads. POST /api/v1/translate/batch accepts up to 16 items in a single synchronous request, with per-item language and glossary overrides as well as an idempotency key.

Asynchronous batch and document translation should instead be used if your workload meets one of these conditions:

• You need completion callbacks or polling status.
• You may exceed synchronous request rate limits.
• You want to work with documents directly.
• Translation requests are not time sensitive.

Check the webhooks docs for more details on working with asynchronous translation.

Rollout checklist

1. Create an API key (see the API keys docs).
2. Send a minimal POST /api/v1/translate request from the playground first.
3. Add auth, request_id logging, and quota checks to your integration.
4. Test structured content modes and placeholder protection on the content you actually ship.
5. Move a share of real traffic and watch error rates and usage.
6. Add synchronous batch for multi-item, time-sensitive workloads and asynchronous batch when you meet the conditions above.

Let us know if you encounter any issues during your rollout. We always want to know what we can improve.