Transliteration
Convert text from one writing script to another while keeping the underlying language identical.
document.transliterate accepts a PDF, DOCX, or PPTX file. It writes the content in targetLanguage, spelled out in the script of scriptLanguage: for example Hindi words in Latin letters, or English words in Devanagari. regionalVariant is not used for transliteration.
| Input | Output (outputFormat) | Credits | Billing operation |
|---|---|---|---|
| docx (default), pdf, epub | 45 per page | translate_text, or ocr_translate with ocr: true | |
| DOCX | docx (default), pdf, epub | 45 per page | translate_text |
| PPTX | pptx (default), pdf | 45 per slide | translate_text |
| Images (uploadIds) | docx (default), pdf, epub | 45 per image | image_translate |
Request Schema
uploadIdstringoptionalUpload ID from POST /v1/uploads of a PDF, DOCX or PPTX. Send either uploadId or uploadIds.
uploadIdsstring[]optionalInstead of uploadId: up to 50 image uploads (JPG, JPEG, PNG, WEBP), in reading order, translated as one document. No duplicates; PDFs can't be mixed in. Images always use OCR.
targetLanguagestringrequiredLanguage of the output words, by name or code. Uses the same language list as Translation.
scriptLanguagestringrequiredLanguage whose writing script the output is written in, by name or code. For example targetLanguage Hindi with scriptLanguage English gives Hindi written in Latin letters (Tum kaise ho?).
tonestringoptionaldefault: professionalWriting style.
additionalInstructionsstringoptionalExtra guidance for the translator, up to 500 characters, for example Keep product names in English.
targetAudiencestringoptionalWho the text is for. Use a preset or your own description, up to 200 characters.
translationStylestringoptionalHow the text should read. Use a preset or your own description, up to 200 characters.
modelstringoptionaldefault: basicTranslation model. pro uses a stronger model for difficult or high-stakes text; the price is the same. premium is accepted as an alias for pro.
ocrbooleanoptionaldefault: falsePDFs only: read the pages with OCR. Use it for scanned PDFs. Images always use OCR; ocr: true on a DOCX or PPTX returns 400.
ocrProfilestringoptionaldefault: europeanWith OCR (scanned PDFs and images): the script family of the source, so the right OCR reader is used. indic is for Indian scripts such as Devanagari, Bengali or Tamil.
outputFormatstringoptionalFile type of the result. PDF, DOCX and images: docx (default), pdf or epub. PPTX: pptx (default) or pdf.
pageLayoutobjectoptionalPDF and DOCX only: page size and print area of the output, in inches. pageWidthIn and pageHeightIn (above 1, up to 40), matterWidthIn and matterHeightIn (above 0.5, up to 40), and optional matterLeftIn and matterTopIn offsets from the top-left corner (centred when left out). The print area must fit inside the page.
webhookUrlstringoptionalTop-level field, next to operation and input. HTTPS URL that receives a signed POST when the job starts running, succeeds or fails. Private and internal hosts are rejected; up to 2048 characters.
| targetLanguage | scriptLanguage | Output |
|---|---|---|
| Hindi | English | Hindi in Latin letters: Tum kaise ho? |
| English | Hindi | English in Devanagari: हाउ आर यू? |
| Arabic | English | Arabic in Latin letters |
Code Example
curl -X POST https://api.transpera.io/v1/jobs \
-H "authorization: Bearer tp_test_..." \
-H "content-type: application/json" \
-H "idempotency-key: $(uuidgen)" \
-d '{
"operation": "document.transliterate",
"input": {
"uploadId": "UPLOAD_ID",
"scriptLanguage": "English",
"targetLanguage": "Hindi",
"tone": "professional"
}
}'Response
POST /v1/jobs answers 201 Created with the new job. status moves from queued to running to succeeded or failed; poll GET /v1/jobs/{id} or use webhookUrl. If the job could not be handed to the worker, it comes back already failed with errorCode enqueue_failed and nothing is charged.
{
"job": {
"id": "8f1c2d3e-4b5a-6789-abcd-ef0123456789",
"operation": "document.transliterate",
"status": "queued",
"createdAt": "2026-11-20T09:30:00.000Z",
"errorCode": null,
"chargedCredits": null
}
}Result
When status is succeeded, result is a file. url is a signed download link valid for one hour; fetch the job again for a fresh link. GET /v1/jobs (the list) never includes result. The file type is the requested outputFormat: by default DOCX, or PPTX for PPTX sources.
{
"job": {
"id": "8f1c2d3e-4b5a-6789-abcd-ef0123456789",
"operation": "document.transliterate",
"status": "succeeded",
"createdAt": "2026-11-20T09:30:00.000Z",
"errorCode": null,
"chargedCredits": 135,
"result": {
"type": "file",
"fileName": "letter_hi.docx",
"url": "https://storage.googleapis.com/...",
"expiresAt": "2026-11-20T10:45:00.000Z"
}
}
}Errors
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_input | Missing targetLanguage or scriptLanguage, both or neither of uploadId and uploadIds, an unknown language, an unsupported file, an outputFormat the source can't produce, ocr or ocrProfile on a DOCX or PPTX, an invalid pageLayout, an unknown model or ocrProfile, text over its length limit, or a non-HTTPS webhookUrl. |
| 402 | insufficient_credits | The wallet can't cover the estimate, or a test key's estimate is above its spend cap. |
| 409 | conflict | The Idempotency-Key was already used with a different input. |