Loading...
We use essential storage to operate Lexel Translate. With your permission, we also use analytics, advertising, and marketing technologies. Read our Cookie Policy.
Loading...
Create an async document job, receive a resumable direct-upload session, then poll status and download the translated result.
Document translation consumes Premium characters, including documents submitted from the signed-in browser interface. Free characters are not used. A remaining Premium balance is required, and the extracted translation input must fit your available balance.
/api/v1/translate/documents/jobsCreate a document job and receive a resumable upload session.
/api/v1/translate/documents/jobs/:jobIdRead document job status.
/api/v1/translate/documents/jobs/:jobId/resultFetch the signed result download URL.
/api/v1/translate/documents/jobs/:jobId/streamStream the completed translated file directly.
Create job example
/api/v1/translate/documents/jobscurl -X POST "https://translate.lexel.ai/api/v1/translate/documents/jobs" \-H "Authorization: Bearer lxl_your_api_key" \-H "Content-Type: application/json" \-d '{"file": {"name": "support-guide.docx","contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document","sizeBytes": 1823440},"job": {"resultTtlSeconds": 86400,"webhookProfileId": "whp_123"},"request": {"request_id": "req_document_demo_001","src": "en-Latn","tgt": "fr-Latn","glossary_id": "gls_support_terms","preserve_placeholders": true}}'
Create response example
{"ok": true,"jobId": "doc_job_123","status": "pending_upload","upload": {"strategy": "gcs_resumable","method": "PUT","resumable": true,"uploadUrl": "https://storage.googleapis.com/upload/storage/v1/b/bucket/o?upload_id=session_123"},"uploadUrl": "https://storage.googleapis.com/upload/storage/v1/b/bucket/o?upload_id=session_123","uploadHeaders": {"content-type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"},"partsUrl": "/api/v1/translate/documents/jobs/doc_job_123/upload-parts","statusUrl": "/api/v1/translate/documents/jobs/doc_job_123","resultUrl": "/api/v1/translate/documents/jobs/doc_job_123/result","cancelUrl": "/api/v1/translate/documents/jobs/doc_job_123/cancel"}
| Field | Type | Required | Description |
|---|---|---|---|
| file.name | string | Yes | Original file name. Used for validation and result naming. |
| file.contentType | string | Yes | Uploaded MIME type. |
| file.sizeBytes | number | Yes | Declared file size in bytes. Used for upload verification and resumable-session setup. |
| file.sha256 | string | No | Optional content checksum for upload integrity validation. |
| job.callbackUrl | https URL | No | Optional one-off callback URL. |
| job.webhookProfileId | string | No | Optional managed callback profile. |
| job.resultTtlSeconds | number | No | Optional result retention in seconds. Defaults to and may not exceed 86400 (24 hours); larger values are rejected with 400. |
| request.request_id | string | Yes | Caller-provided request trace ID. |
| request.src | language tag | "" | No | Optional source language or auto-detect. |
| request.tgt | language tag | Yes | Target language for the document translation job. |
| request.content_mode | plain | markdown | html | json | csv | No | Optional explicit translation mode. TXT/MD/HTML/JSON/CSV infer their matching mode. DOCX/PPTX/PDF extract plain text and only support plain mode. |
| request.glossary_id | string | No | Stored glossary selection pinned at job creation. |
| request.do_not_translate | string[] | No | Protected terms for the document extraction and translation flow. |
| request.preserve_placeholders | boolean | No | Optional placeholder detection flag. Disabled by default. |
| Field | Type | Required | Description |
|---|---|---|---|
| status | pending_upload | upload_received | extracting | translating | assembling | completed | failed | canceled | Yes | Current document job state. |
| summary.fileName | string | Yes | Original file name. |
| summary.sourceFormat | txt | md | html | json | csv | docx | pptx | pdf | No | Detected source artifact format. |
| summary.targetFormat | txt | md | html | json | csv | No | Delivered result format. DOCX/PPTX/PDF currently finalize as translated UTF-8 text files. |
| summary.expectedSizeBytes | number | No | Declared upload size. |
| summary.uploadedSizeBytes | number | null | No | Observed uploaded size when available. |
| summary.inputCharacters | number | null | No | Extracted source character count. |
| summary.outputCharacters | number | null | No | Translated output character count. |
| callback | object | No | Callback delivery status. |
Resumable upload PUT example
curl -X PUT "https://storage.googleapis.com/upload/storage/v1/b/bucket/o?upload_id=session_123" \-H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \--data-binary "@support-guide.docx"
Send the file bytes directly to uploadUrl. The example above uploads the whole file in one PUT.For chunked uploads, send each chunk as the body of a PUT with Content-Range until the upload is finalized:Content-Range: bytes START-END/TOTALIf the upload session expires before completion, call partsUrl to mint a fresh resumable session for the same pending job.
Result response example
{"ok": true,"jobId": "doc_job_123","status": "completed","result": {"fileName": "support-guide.translated.txt","contentType": "text/plain; charset=utf-8","sizeBytes": 2012240,"downloadUrl": "https://storage.example.com/presigned-download","streamUrl": "/api/v1/translate/documents/jobs/doc_job_123/stream","expiresAt": "2026-06-30T19:00:00.000Z"},"usage": {"input_characters": 180932,"output_characters": 194287},"warnings": []}