Batch translation

Translate many text segments in one async job. Each segment keeps an optional id that is echoed in the response.

For 10 or fewer segments that must return immediately, use synchronous segments on Translate instead of this async API.

Flow

1. POST /v1/translate/batch with a JSON body (returns 202 and a job id)
2. GET /v1/translate/batch/{id} every few seconds until status is done, failed, or cancelled
3. When status is done, the same response includes translated segments

Use POST /v1/translate/batch/{id}/cancel to stop a running job.

All batch jobs on Mansa run asynchronously (including small batches).

Request parameters

Maximum 100 segments per job. Auto-detect is not supported for the source language.

Create response

{
  "context": "ok",
  "data": {
    "id": "abc123-xyz789",
    "status": "running",
    "segment_count": 3,
    "source_chars": 42
  }
}

Status and result

While status is running, poll GET /v1/translate/batch/{id}. Progress fields completed_segments and total_segments are included when available.

When status is done:

{
  "context": "ok",
  "data": {
    "id": "abc123-xyz789",
    "status": "done",
    "completed_segments": 3,
    "total_segments": 3,
    "segments": [
      {
        "text": "Hello",
        "translated_text": "Hujambo",
        "id": "1"
      }
    ]
  }
}

Supported languages

Batch translation uses the same language catalog as Translate.

Errors and billing

Invalid segments, missing languages, and segment limits return invalid_request. Insufficient Mansa Credits return insufficient_credit.

Usage is charged when the job completes, based on the source character count across all segments (same per-character rate as text translation). See Pricing.

curl --fail-with-body "$MANSA_API_BASE_URL/v1/translate/batch" \
  -H "Authorization: Bearer $MANSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "English",
  "to": "Swahili",
  "segments": [
    {
      "id": "1",
      "text": "Hello"
    },
    {
      "id": "2",
      "text": "How are you?"
    }
  ],
  "tone": "natural"
}'

{
  "context": "ok",
  "data": {
    "id": "abc123-xyz789",
    "status": "running",
    "segment_count": 2,
    "source_chars": 19
  }
}