POST
/
v2
/
document
curl --request POST \
  --url https://api.deepl.com/v2/document \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form target_lang=DE \
  --form file=@example-file
{
  "document_id": "04DE5AD98A02647D83285A36021911C6",
  "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"
}

Authorizations

​
Authorization
string
header
required

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

Body

multipart/form-data
​
target_lang
enum<string>
required

The language into which the text should be translated.

Available options:
AR,
BG,
CS,
DA,
DE,
EL,
EN-GB,
EN-US,
ES,
ET,
FI,
FR,
HU,
ID,
IT,
JA,
KO,
LT,
LV,
NB,
NL,
PL,
PT-BR,
PT-PT,
RO,
RU,
SK,
SL,
SV,
TR,
UK,
ZH,
ZH-HANS,
ZH-HANT
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
  • pdf - Portable Document Format
  • htm / html - HTML Document
  • txt - Plain Text Document
  • xlf / xliff - XLIFF Document, version 2.1
  • srt - SRT Document
​
source_lang
enum<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.

Available options:
AR,
BG,
CS,
DA,
DE,
EL,
EN,
ES,
ET,
FI,
FR,
HU,
ID,
IT,
JA,
KO,
LT,
LV,
NB,
NL,
PL,
PT,
RO,
RU,
SK,
SL,
SV,
TR,
UK,
ZH
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.

​
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.

Example:

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

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"