Your privacy choices

We use essential storage to operate Lexel Translate. With your permission, we also use analytics, advertising, and marketing technologies. Read our Cookie Policy.

Synchronous batch

Translate up to 16 independent items in one synchronous batch request.

Endpoint

POST/api/v1/translate/batch

Independent synchronous batch endpoint.

Request example

POST/api/v1/translate/batch

curl -X POST "https://translate.lexel.ai/api/v1/translate/batch" \
  -H "Authorization: Bearer lxl_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-demo-001" \
  -d '{
  "request_id": "req_batch_demo_001",
  "content_mode": "plain",
  "preserve_placeholders": true,
  "input": {
    "items": [
      {
        "id": "item_1",
        "txt": "Hello world",
        "src": "en-Latn",
        "tgt": "ja-Jpan"
      },
      {
        "id": "item_2",
        "txt": "How are you, {name}?",
        "src": "en-Latn",
        "tgt": "fr-Latn",
        "do_not_translate": [
          "{name}"
        ],
        "glossary_id": "gls_support_terms"
      }
    ]
  }
}'

Response example

json

{
  "ok": true,
  "request_id": "req_batch_demo_001",
  "operation": "translate",
  "output": {
    "kind": "batch",
    "batch": [
      {
        "id": "item_1",
        "ok": true,
        "translation": "こんにちは世界",
        "src": "en-Latn",
        "tgt": "ja-Jpan",
        "detection_confidence": 0.99,
        "inference_latency": 118
      },
      {
        "id": "item_2",
        "ok": false,
        "error": "Premium characters exhausted."
      }
    ]
  },
  "usage": {
    "input_characters": 31,
    "output_characters": 7
  },
  "warnings": [],
  "summary": {
    "total_items": 2,
    "successful_items": 1,
    "failed_items": 1
  }
}

Request fields

Field	Type	Required	Description
request_id	string	Yes	Caller-provided request trace ID.
content_mode	auto \| plain \| markdown \| html \| json \| xml \| yaml \| csv	No	Root default content mode. HTML text and selected attribute values, or JSON string values, are translated while tags and keys stay intact.
split_input	0 \| 1 \| 2	No	0 off, 1 balanced (default), 2 aggressive. Splitting can reduce latency with generally minimal impact on translation quality.
preserve_placeholders	boolean	No	Root default placeholder detection flag for items that do not override it.
metadata	object	No	Caller-defined JSON metadata for the batch request.
input.items	array (max 16 items)	Yes	Ordered synchronous batch items. Each item can override language pair, glossary selection, and protection settings.
input.items[].id	string	Yes	Caller-provided item ID returned with the result item.
input.items[].txt	string	Yes	Text to translate.
input.items[].src	language tag \| ""	No	Per-item source language. Empty string requests auto-detect.
input.items[].tgt	language tag	Yes	Per-item target language.
input.items[].glossary_id	string	No	Per-item stored glossary selection.
input.items[].glossary_group_ids	string[]	No	Per-item enabled glossary groups.
input.items[].glossary_item_ids	string[]	No	Per-item enabled glossary items.
input.items[].glossary	object	No	Per-item inline glossary.
input.items[].do_not_translate	string[]	No	Per-item protected terms.
metadata.legacy_idempotency_key	string	No	Optional body alias for the idempotency key. The Idempotency-Key header is also accepted.

Response fields

Field	Type	Required	Description
ok	boolean	Yes	True when the batch request itself is accepted and processed.
output.kind	"batch"	Yes	Batch output discriminator.
output.batch[]	array	Yes	Ordered per-item results.
output.batch[].id	string	Yes	Caller item ID.
output.batch[].ok	boolean	Yes	Whether the item translated successfully.
output.batch[].translation	string	No	Translated text when ok is true.
output.batch[].error	string	No	Item-level error message when ok is false.
summary.total_items	number	Yes	Total submitted items.
summary.successful_items	number	Yes	Number of successful item translations.
summary.failed_items	number	Yes	Number of failed item translations.

Behavior

Order is preserved. Each item succeeds or fails independently. Mixed language pairs, mixed glossary selections, and mixed do_not_translate values are supported.
Placeholder detection is off by default. Set preserve_placeholders: true at the root or item level only when you want placeholder-like values detected and protected.

Synchronous batch

Translate up to 16 independent items in one synchronous batch request.

Endpoint

POST/api/v1/translate/batch

Independent synchronous batch endpoint.

Request example

POST/api/v1/translate/batch

curl -X POST "https://translate.lexel.ai/api/v1/translate/batch" \
  -H "Authorization: Bearer lxl_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-demo-001" \
  -d '{
  "request_id": "req_batch_demo_001",
  "content_mode": "plain",
  "preserve_placeholders": true,
  "input": {
    "items": [
      {
        "id": "item_1",
        "txt": "Hello world",
        "src": "en-Latn",
        "tgt": "ja-Jpan"
      },
      {
        "id": "item_2",
        "txt": "How are you, {name}?",
        "src": "en-Latn",
        "tgt": "fr-Latn",
        "do_not_translate": [
          "{name}"
        ],
        "glossary_id": "gls_support_terms"
      }
    ]
  }
}'

Response example

json

{
  "ok": true,
  "request_id": "req_batch_demo_001",
  "operation": "translate",
  "output": {
    "kind": "batch",
    "batch": [
      {
        "id": "item_1",
        "ok": true,
        "translation": "こんにちは世界",
        "src": "en-Latn",
        "tgt": "ja-Jpan",
        "detection_confidence": 0.99,
        "inference_latency": 118
      },
      {
        "id": "item_2",
        "ok": false,
        "error": "Premium characters exhausted."
      }
    ]
  },
  "usage": {
    "input_characters": 31,
    "output_characters": 7
  },
  "warnings": [],
  "summary": {
    "total_items": 2,
    "successful_items": 1,
    "failed_items": 1
  }
}

Request fields

Field	Type	Required	Description
request_id	string	Yes	Caller-provided request trace ID.
content_mode	auto \| plain \| markdown \| html \| json \| xml \| yaml \| csv	No	Root default content mode. HTML text and selected attribute values, or JSON string values, are translated while tags and keys stay intact.
split_input	0 \| 1 \| 2	No	0 off, 1 balanced (default), 2 aggressive. Splitting can reduce latency with generally minimal impact on translation quality.
preserve_placeholders	boolean	No	Root default placeholder detection flag for items that do not override it.
metadata	object	No	Caller-defined JSON metadata for the batch request.
input.items	array (max 16 items)	Yes	Ordered synchronous batch items. Each item can override language pair, glossary selection, and protection settings.
input.items[].id	string	Yes	Caller-provided item ID returned with the result item.
input.items[].txt	string	Yes	Text to translate.
input.items[].src	language tag \| ""	No	Per-item source language. Empty string requests auto-detect.
input.items[].tgt	language tag	Yes	Per-item target language.
input.items[].glossary_id	string	No	Per-item stored glossary selection.
input.items[].glossary_group_ids	string[]	No	Per-item enabled glossary groups.
input.items[].glossary_item_ids	string[]	No	Per-item enabled glossary items.
input.items[].glossary	object	No	Per-item inline glossary.
input.items[].do_not_translate	string[]	No	Per-item protected terms.
metadata.legacy_idempotency_key	string	No	Optional body alias for the idempotency key. The Idempotency-Key header is also accepted.

Response fields

Field	Type	Required	Description
ok	boolean	Yes	True when the batch request itself is accepted and processed.
output.kind	"batch"	Yes	Batch output discriminator.
output.batch[]	array	Yes	Ordered per-item results.
output.batch[].id	string	Yes	Caller item ID.
output.batch[].ok	boolean	Yes	Whether the item translated successfully.
output.batch[].translation	string	No	Translated text when ok is true.
output.batch[].error	string	No	Item-level error message when ok is false.
summary.total_items	number	Yes	Total submitted items.
summary.successful_items	number	Yes	Number of successful item translations.
summary.failed_items	number	Yes	Number of failed item translations.

Behavior

Order is preserved. Each item succeeds or fails independently. Mixed language pairs, mixed glossary selections, and mixed do_not_translate values are supported.
Placeholder detection is off by default. Set preserve_placeholders: true at the root or item level only when you want placeholder-like values detected and protected.