Documentation

Everything you need — whether you run the Discord bot or build on the API.

Endpoint reference

v1 exposes two 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).

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.
401	invalid_key	Missing, revoked, or malformed API key.
402	quota_exceeded	Included characters used up and overage disabled on your account.
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.