APIsDocument Translation

Create Document Translation Job

View as Markdown
## Document Translation Create a document translation job. Returns a `job_id` and a short-lived signed `upload_url`. **Flow:** 1. `POST /translate/document/jobs` with source/target languages and options. 2. `PUT` the raw file bytes to `upload_url` with header `Content-Type: <mime>`. 3. `POST /translate/document/jobs/{job_id}/start` to begin the pipeline. 4. Poll `GET /translate/document/jobs/{job_id}/live-status` until translation completes. 5. `POST /translate/document/jobs/{job_id}/export?lang=<code>` to enqueue an async export for each target language (exports in the uploaded file's format by default). 6. Poll `GET /translate/document/jobs/{job_id}/export/status` until `export_state` is `Completed`, then download from `download_url`. A single job translates into every language in `target_language_codes`. Exports run asynchronously — do not expect the download URL in the trigger response.

Authentication

api-subscription-keystring
API Key authentication via header

Request

This endpoint expects an object.
source_language_codeenumRequired

Source language (BCP-47).

original_filenamestringRequired>=1 character

Original filename with extension. Supported: .pdf, .doc, .docx, .odt, .xls, .xlsx, .ods, .ppt, .pptx, .odp, .html, .xhtml, .mhtml.

target_language_codeslist of enumsRequired

Target languages (BCP-47).

job_namestringOptional1-255 characters

Optional human-readable job name. Defaults to original_filename when omitted.

genreenum or nullOptional

Genre enum name (e.g. NON_FICTION). Use the enum constant name, not the human-readable label.

use_native_numeralsboolean or nullOptional

use_native_numerals is an optional parameter with three options:

  • null (default): Uses the application default.
  • false: Uses international numerals (0-9).
  • true: Uses language-specific native numerals.

Example:

  • If international numerals are used, numbers appear as regular digits (0-9). For example: मेरा phone number है: 9840950950.
  • If native numerals are used, numbers appear in the target script. For example: मेरा phone number है: ९८४०९५०९५०.
style_guidelinesstring or nullOptional

Global tone, terminology, and formatting instructions (up to ~4000 characters). Applies to every target language.

language_specific_guidelinesmap from strings to strings or nullOptional

Per-language overrides (up to ~4000 characters each). Keys must match entries in target_language_codes.

Response

Job created.
job_idstring
Unique job identifier.
upload_urlstring
Signed URL for direct file upload.
expires_in_hoursinteger
Hours until the upload URL expires.
source_language_codestring
Echo of request source language.
target_language_codeslist of strings
Echo of target languages.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
500
Internal Server Error