Skip to main content
POST

Authorizations

​
Authorization
string
header
default:DeepL-Auth-Key
required

Authentication with Authorization header and DeepL-Auth-Key authentication scheme. Example: DeepL-Auth-Key <api-key>

Body

multipart/form-data
​
target_lang
string
required

The language into which the text should be translated.

For the full list of supported target languages, see supported languages or query the GET /v3/languages endpoint.

Example:

"DE"

​
file
file
required

The document file to be translated. The file name should be included in this part's content disposition. As an alternative, the filename parameter can be used. The following file types and extensions are supported:

  • docx - Microsoft Word Document
  • pptx - Microsoft PowerPoint Document
  • xlsx - Microsoft Excel Document
  • xlsm - Microsoft Excel Macro-Enabled Workbook (currently in beta)
  • pdf - Portable Document Format
  • htm / html - HTML Document
  • txt - Plain Text Document
  • xlf / xliff - XLIFF Document (versions 1.2, 2.0, and 2.1)
  • srt - SRT Document
  • vtt - WebVTT Subtitle Document (currently in beta)
  • idml - Adobe InDesign Markup Language
  • xml - XML Document
  • json - JSON Document
  • yaml / yml - YAML Document (currently in beta)
  • properties - Java Properties Document (currently in beta)
  • strings - iOS/macOS Strings Document (currently in beta)
  • md / markdown - Markdown Document (currently in beta)
  • dita - DITA topic (Darwin Information Typing Architecture)
  • mif - Adobe FrameMaker Interchange Format
  • zip - SCORM Package (e-learning content, currently in beta)
  • odt - OpenDocument Text Document (currently in beta)
  • rtf - Rich Text Format Document (currently in beta)
  • resx - .NET Resource Document (currently in beta)
  • jpeg / jpg / png - Image (currently in beta)
​
source_lang
string

Language of the text to be translated. If this parameter is omitted, the API will attempt to detect the language of the text and translate it.

For the full list of supported source languages, see supported languages or query the GET /v3/languages endpoint.

Example:

"EN"

​
filename
string

The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition.

​
output_format
string

File extension of desired format of translated file, for example: docx. If unspecified, by default the translated file will be in the same format as the input file.

​
input_conversion_options
string

Comma-separated list of key:value conversion options, prefixed with a version, that control how the input document is converted before translation. For example: version:1,suppress-image-types:all.

Supported keys:

  • suppress-image-types - Leaves the specified types of images embedded in the document untranslated. The value is a hyphen-separated list of image content types (for example logo-photo suppresses logos and photos), or all to suppress every embedded image. Recognized image content types: logo, icon, decorative, barcode, formula, signature, handwriting, stamp, screenshot, diagram, chart, photo, illustration, comic, music, infographic, table, text, other, unknown. Only pptx documents support this key.
  • json-placeholders - Controls how brace-delimited placeholders in json string values are handled. protect (the default) keeps identifier-shaped placeholders such as {stars} or {{userName}} verbatim so they are not translated; translate translates them along with the surrounding text. ICU MessageFormat skeletons such as {count, plural, one {# item} other {# items}} are always protected, with only the branch text translated, in both modes. Multi-word groups such as {see note} are treated as translatable text in both modes.

For other file types this parameter is ignored. Unrecognized keys are ignored.

Example:

"version:1,suppress-image-types:all"

​
formality
enum<string>
default:default

Sets whether the translated text should lean towards formal or informal language. This feature is only available for certain target languages. Setting this parameter with a target language that does not support formality will fail, unless one of the prefer_... options are used. Possible options are:

  • default (default)
  • more - for a more formal language
  • less - for a more informal language
  • prefer_more - for a more formal language if available, otherwise fallback to default formality
  • prefer_less - for a more informal language if available, otherwise fallback to default formality
Available options:
default,
more,
less,
prefer_more,
prefer_less
Example:

"prefer_more"

​
glossary_id
string

A unique ID assigned to a glossary. To check glossary support for a language pair, call GET /v3/languages?resource=translate_document and verify the glossary feature key is present on both the source and target language.

Cannot be used together with glossary_ids.

Example:

"def3a26b-3e84-45b3-84ae-0c0aaf3525f7"

​
glossary_ids
string[]

Comma-separated list of up to 5 glossary IDs to use for the translation. Each glossary's matching terms are applied to the translated document. May also be sent as a repeated parameter.

Important: This requires the source_lang parameter to be set. Every listed glossary must contain a dictionary for the requested language pair.

Cannot be used together with glossary_id.

Maximum array length: 5
​
style_id
string

Specify the style rule list to use for the translation.

Important: The target language has to match the language of the style rule list. A list created for a root language (for example en) applies to that language and all of its variants (EN-GB, EN-US). A list created for a variant (for example en-GB) applies only when target_lang is that variant.

Example:

"7ff9bfd6-cd85-4190-8503-d6215a321519"

​
translation_memory_id
string<uuid>

A unique ID assigned to a translation memory.

Example:

"a74d88fb-ed2a-4943-a664-a4512398b994"

​
translation_memory_threshold
integer
default:75

The minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher). A value below 50 is treated as 50.

Required range: 0 <= x <= 100
Example:

75

​
enable_watermark
boolean
default:false

When true, adds a "Translated by DeepL" watermark to the translated document.

Only supported for docx and pdf output. For all other output formats the parameter is ignored and the document is returned without a watermark.

​
enable_quality_evaluation
boolean
default:false

(beta) When true, DeepL also evaluates the finished translation and returns a quality_evaluation_job_id. Poll GET /v1/quality-evaluations/{job_id} with it for a per-segment report of translation issues. The translation itself is unaffected.

Important: Available to select customers; contact your customer success manager to enable it. Supported for docx, pptx, pdf, srt, idml, xml, dita, mif, and XLIFF 2.1 uploads, and for the supported language pairs only.

Rejected before the upload is accepted: 403 if quality evaluation is not enabled for the account, 400 for an ineligible file type, an unsupported language pair, or a value other than true or false.

​
enable_beta_languages
boolean
default:false
deprecated

This parameter is maintained for backward compatibility and has no effect.

Response

The document function returns a JSON object containing the ID and encryption key assigned to the uploaded document. Once received by the server, uploaded documents are immediately encrypted using a uniquely generated encryption key. This key is not persistently stored on the server. Therefore, it must be stored by the client and sent back to the server with every subsequent request that refers to this particular document.

​
document_id
string

A unique ID assigned to the uploaded document and the translation process. Must be used when referring to this particular document in subsequent API requests.

Example:

"04DE5AD98A02647D83285A36021911C6"

​
document_key
string

A unique key that is used to encrypt the uploaded document as well as the resulting translation on the server side. Must be provided with every subsequent API request regarding this particular document.

Example:

"0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"

​
quality_evaluation_job_id
string

(beta) A unique ID assigned to the quality evaluation. Returned only when the request set enable_quality_evaluation=true. Use it to retrieve the report from GET /v1/quality-evaluations/{job_id}.

Example:

"04DE5AD98A02647D83285A36021911C6"