Document Translation API
Upload a document file, monitor the translation job in the background, and download the translated document once complete. Supported formats: DOCX, TXT, CSV, and XLSX.
Overview & Flow
Document translation is an asynchronous multi-stage process:
- Upload: Submit a file via
POST /v1/translate/file(returns HTTP202 Acceptedwith ajobId). - Poll Status: Query
GET /v1/translate/file/{jobId}untilstatusbecomesdone,failed, orcancelled. - Download: Fetch the translated document via
GET /v1/translate/file/{jobId}/download. - Cancel (Optional): Abort an in-progress job via
POST /v1/translate/file/{jobId}/cancel.
[!NOTE] All endpoints require authentication via your API key in the
Authorizationheader:
Authorization: Bearer <YOUR_API_KEY>
1. Initiate Translation
POST /v1/translate/file
Submit a file using multipart/form-data. Alternatively, remote files can be submitted as application/json with a fileUrl.
Multipart Form Fields
Example Request (cURL)
curl -X POST https://api.mansa.ai/v1/translate/file \
-H "Authorization: Bearer mansa_live_..." \
-F "file=@financial_report.docx" \
-F "from=en" \
-F "to=yor" \
-F "context=Formal financial report for shareholders"Success Response (202 Accepted)
All successful API responses are wrapped in a standard response envelope (data):
{
"context": "OK",
"data": {
"jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"fileType": "docx",
"segmentCount": 84,
"message": "File translation started in the background."
},
"meta": null
}2. Check Job Status
GET /v1/translate/file/{jobId}
Poll this endpoint every 2 to 5 seconds to track translation progress.
Response Attributes
Example Response (200 OK)
{
"context": "OK",
"data": {
"status": "running",
"fileType": "docx",
"stage": "translating",
"completedSegments": 42,
"totalSegments": 84,
"error": null
},
"meta": null
}3. Download Translated Document
GET /v1/translate/file/{jobId}/download
Downloads the translated binary document once the job reaches "status": "done".
Query Parameters
HTTP Response Codes
200 OK: Returns the translated document binary stream with appropriateContent-TypeandContent-Dispositionheaders (e.g.,financial_report_yor_translated.docx).202 Accepted: The job is still processing. Returns{ "message": "Job is not complete yet" }.400 Bad Request: The job was cancelled. Returns{ "error": "Job was cancelled" }.422 Unprocessable Entity: The job failed or generated no valid segments. Returns{ "error": "<reason>" }.
Example Request
curl -X GET "https://api.mansa.ai/v1/translate/file/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/download" \
-H "Authorization: Bearer mansa_live_..." \
--output "financial_report_yor.docx"4. Cancel a Translation Job
POST /v1/translate/file/{jobId}/cancel
Cancels an in-progress or queued translation job.
Example Response (200 OK)
{
"context": "OK",
"data": {
"message": "File translation job cancelled successfully"
},
"meta": null
}Extraction Rules & Limits
The extraction engine parses incoming files into discrete translation segments:
Quotas & Limits
- Segment Cap: Maximum 1,100 segments per file. Files exceeding this limit are rejected with HTTP
422. - DOCX Volume Limit: Capped at 10 DOCX jobs per account per rolling 24 hours.
- File Size Limit: Maximum 10 MB per uploaded file.
Errors & Status Codes
Errors return RFC-7807 compliant error envelopes:
{
"type": "about:blank",
"title": "VALIDATION_ERROR",
"isError": true,
"detail": "File size exceeds limit of 10MB.",
"invalidParams": [],
"context": ""
}Billing & Credits
- Usage is billed when the translation job completes.
- Charges are calculated strictly based on the total source character count successfully translated from the extracted file segments (billed at standard translation character pricing).