POST /v1/translate reference

POST https://api.langapi.xyz/v1/translate

This is the endpoint that does the work. It accepts a JSON body or a URL-encoded form and always responds with JSON.

Body parameters

Two target codes are aliases: EN resolves to EN-US and PT to PT-PT. Name the variant explicitly if the distinction matters to you.

Validation order

Checks run in a fixed sequence and stop at the first failure. Knowing the order helps when a request fails for more than one reason.

1. text present, non-empty, at most 50 items — otherwise validation_error

or too_many_texts.

1. Total characters within your plan's per-request limit — otherwise

text_too_long.

1. target_lang present and supported — otherwise validation_error or

invalid_target_lang.

1. source_lang, if given, supported — otherwise invalid_source_lang.
2. formality is one of the five values, and more/less is only used on a

target that supports it — otherwise validation_error.

1. tag_handling, context length, and finally the glossary: it must exist

(glossary_not_found), source_lang must be set and the language pair must match (validation_error).

Only after all of that are characters reserved against your quota.

Worked example

A Spanish product description into British English, with a glossary that pins the product name and context that tells the engine what kind of text it is.

curl https://api.langapi.xyz/v1/translate \
  -X POST \
  -H "Authorization: Bearer la_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "text": ["La funda protege el teléfono contra golpes y arañazos."],
        "source_lang": "ES",
        "target_lang": "EN-GB",
        "glossary_id": "01JAX1F7Q0M2ZK8WDN5R3TB9VE",
        "context": "Short product description in an online shop for phone accessories."
      }'

{
  "translations": [
    {
      "detected_source_language": "ES",
      "text": "The case protects the phone against knocks and scratches."
    }
  ],
  "request_id": "01JAX1G2H4N6PQ8S0T2V4W6X8Z",
  "characters": 54,
  "engine": { "prompt_tokens": 88, "completion_tokens": 17, "total_tokens": 105 }
}

Response body

Response headers

Form-encoded bodies

Without a JSON content type the body is read as application/x-www-form-urlencoded. Repeat text for each entry; text[] is accepted as well.

curl https://api.langapi.xyz/v1/translate \
  -H "Authorization: Bearer la_live_xxxxxxxx" \
  --data-urlencode "text=Reset password" \
  --data-urlencode "text=Remember me on this device" \
  --data-urlencode "target_lang=PL"

Plan limits

Counting characters

The count is mb_strlen over every entry of text, summed. Letters, digits, spaces, line breaks, punctuation and every character of HTML or XML markup are included. context is excluded. The same function produces the reservation, the characters field and the usage record, so the three cannot diverge.

Caching

Each entry in text is cached separately. The cache key covers the text itself, the source language (or "auto"), the target language, formality, the glossary id together with its version, tag_handling, preserve_formatting and context. Change any of them and the entry is translated afresh. Cached entries are still charged; the reservation happens before the cache is consulted.

Engine failures

The engine is called with a 30-second timeout. A transport error, a 5xx or a 429 from the engine is retried once internally. If the second attempt fails too, the reservation is rolled back and you receive 503 with the code engine_unavailable and Retry-After: 5. Nothing is charged for that request.