Documentation

Everything you need to integrate the Lingua translation API.

Endpoint reference

v1 exposes three endpoints. All requests and responses are JSON (UTF-8).

POST/v1/translate

Translates a single piece of text. Source language is auto-detected unless source is provided.

Request body

`text`	string	required	The text to translate. Up to 5,000 characters per request. Characters are metered against your plan's included volume.
`target`	string	required	Target language code (e.g. `ja`, `pt-BR`). See `GET /v1/languages`.
`source`	string	optional	Source language code. Omit for automatic detection.
`engine`	string	optional	`libre` (default) or `deepl`(Growth plan and above). Requests fall back to your plan's best available engine.

Request examples

curl -X POST https://api.lingua-api.com/v1/translate \
  -H "Authorization: Bearer $LINGUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hello world", "target": "ja" }'

# { "text": "こんにちは世界", "detected": "en", "confidence": 0.92,
#   "engine": "libre", "characters": 11 }

Response

{
  "text": "こんにちは世界",
  "detected": "en",
  "confidence": 0.92,
  "engine": "libre",
  "characters": 11
}

Response fields

`text`	string	The translated text.
`detected`	string	Source language as a lower-case base code (e.g. `en`). When you pin `source`, this echoes it back.
`confidence`	number \| null	Confidence factor for the detected source language, normalized to `0`–`1`. `1` when you pinned `source` (no detection performed); `null` when the engine does not report a score (currently DeepL auto-detection). Treat values below ~`0.5` as unreliable — short or mixed-language text detects poorly; retry with an explicit `source`.
`engine`	string	Engine that served the request: `libre` or `deepl`. May differ from the requested engine if your plan fell back.
`characters`	number	Characters metered against your plan for this request (input length).

POST/v1/translate/batch

Translates many strings into one target language in a single call. The batch is atomic — you get every translation or an error — and counts as one hit against your per-second rate limit regardless of item count.

Request body

`texts`	string[]	required	1–100 strings to translate. Each must be non-empty and up to 5,000 characters; the batch may total up to 20,000 characters. Duplicates are allowed and metered separately. Index-aligned with `translations` in the response.
`target`	string	required	Target language code for every item — same rules as above.
`source`	string	optional	Source language code for every item — same rules as above. Omit for per-item detection.
`engine`	string	optional	Engine for every item — same rules as above.

Request examples

curl -X POST https://api.lingua-api.com/v1/translate/batch \
  -H "Authorization: Bearer $LINGUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "texts": ["Hello", "Goodbye"], "target": "ja", "source": "en" }'

# { "translations": [
#     { "text": "こんにちは", "detected": "en", ... },
#     { "text": "さようなら", "detected": "en", ... }
#   ],
#   "engine": "libre", "characters": 12 }

Response

{
  "translations": [
    { "text": "こんにちは", "detected": "en", "confidence": 0.92, "engine": "libre", "characters": 5 },
    { "text": "さようなら", "detected": "en", "confidence": 0.95, "engine": "libre", "characters": 7 }
  ],
  "engine": "libre",
  "characters": 12
}

Response fields

`translations`	object[]	One result per input, in the same order as `texts`. Each has the fields documented above (`text`, `detected`, `confidence`, `engine`, `characters`); `detected` and `confidence` are computed per item.
`engine`	string	Engine that served the batch: `libre` or `deepl`.
`characters`	number	Total characters metered for the batch — the sum of the items' `characters`.

Limits & behaviour

Atomic: if any item fails validation or any upstream call fails, the whole batch returns an error and nothing is metered.
One batch is one hit against the per-second rate limit, however many items it carries.
With overage disabled, a batch whose total exceeds your included remaining is rejected up front with 402 quota_exceeded — check X-Usage-Included-Remaining and retry with a smaller batch.
Each item is cached exactly like a single /v1/translate call, so single and batch requests share one 24 h cache. Cache hits are still metered.
Large batches can take up to the 15 s upstream timeout plus overhead — set a client timeout of at least 30 s.

GET/v1/languages

Lists all supported languages. Free to call — does not count against usage.

{
  "languages": [
    { "code": "en-US", "name": "English (US)" },
    { "code": "ja", "name": "Japanese" },
    ...
  ]
}

Errors

Errors use conventional HTTP status codes with a JSON body:

{ "error": { "code": "quota_exceeded", "message": "Monthly included characters exhausted and overage is disabled." } }

Status	Code	Meaning
400	invalid_request	Missing/invalid fields, unsupported language code, text too long. For batches, item-level messages name the index (`texts[3]`).
401	invalid_key	Missing, revoked, or malformed API key.
402	quota_exceeded	Included characters used up and overage disabled on your account.
413	—	Request body over 1 MB. Returned by the body parser before validation, so the body is `{ statusCode, message }` rather than the `error` envelope.
429	rate_limited	Requests-per-second cap hit — check the `Retry-After` header.
503	engine_unavailable	Upstream engine outage; retry with backoff or a different engine.