Upload and Translate a Document Run in API Explorer
This call uploads a document and queues it for translation. The call returns once the upload is complete, returning a document ID and key which can be used to query the translation status and to download the translated document once translation is complete.
Because the request includes a file upload, it must be an HTTP POST request with content type multipart/form-data.
Please be aware that the uploaded document is automatically removed from the server once the translated document has been downloaded. You have to upload the document again in order to restart the translation.
The maximum upload limit for documents is available here and may vary based on API plan and document type.
You may specify the glossary to use for the document translation using the glossary_id parameter.
Important: This requires the source_lang parameter to be set and the language pair of the glossary has to match the language pair of the request.
Body
Required
-
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.
Note: Some languages only work with
model_typeset toquality_optimized. See supported languages for more details.Values are
ACE,AF,AN,AR,AS,AY,AZ,BA,BE,BG,BHO,BN,BR,BS,CA,CEB,CKB,CS,CY,DA,DE,EL,EN,EO,ES,ET,EU,FA,FI,FR,GA,GL,GN,GOM,GU,HA,HE,HI,HR,HT,HU,HY,ID,IG,IS,IT,JA,JV,KA,KK,KMR,KO,KY,LA,LB,LMO,LN,LT,LV,MAI,MG,MI,MK,ML,MN,MR,MS,MT,MY,NB,NE,NL,OC,OM,PA,PAG,PAM,PL,PRS,PS,PT,QU,RO,RU,SA,SCN,SK,SL,SQ,SR,ST,SU,SV,SW,TA,TE,TG,TH,TK,TL,TN,TR,TS,TT,UK,UR,UZ,VI,WO,XH,YI,YUE,ZH, orZU. -
The language into which the text should be translated.
Note: Some languages only work with
model_typeset toquality_optimized. See supported languages for more details.Values are
ACE,AF,AN,AR,AS,AY,AZ,BA,BE,BG,BHO,BN,BR,BS,CA,CEB,CKB,CS,CY,DA,DE,EL,EN,EN-GB,EN-US,EO,ES,ES-419,ET,EU,FA,FI,FR,GA,GL,GN,GOM,GU,HA,HE,HI,HR,HT,HU,HY,ID,IG,IS,IT,JA,JV,KA,KK,KMR,KO,KY,LA,LB,LMO,LN,LT,LV,MAI,MG,MI,MK,ML,MN,MR,MS,MT,MY,NB,NE,NL,OC,OM,PA,PAG,PAM,PL,PRS,PS,PT,PT-BR,PT-PT,QU,RO,RU,SA,SCN,SK,SL,SQ,SR,ST,SU,SV,SW,TA,TE,TG,TH,TK,TL,TN,TR,TS,TT,UK,UR,UZ,VI,WO,XH,YI,YUE,ZH,ZH-HANS,ZH-HANT, orZU. -
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 Documentpptx- Microsoft PowerPoint Documentxlsx- Microsoft Excel Documentpdf- Portable Document Formathtm / html- HTML Documenttxt- Plain Text Documentxlf / xliff- XLIFF Document, version 2.1srt- SRT Documentjpeg / jpg / png- Image
-
The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition.
-
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.Note: Not all combinations of input file and translation file extensions are permitted. See Document Format Conversions for the permitted combinations.
-
Sets whether the translated text should lean towards formal or informal language. This feature currently only works for target languages
DE(German),FR(French),IT(Italian),ES(Spanish),ES-419(Latin American Spanish),NL(Dutch),PL(Polish),PT-BRandPT-PT(Portuguese),JA(Japanese), andRU(Russian). Learn more about the plain/polite feature for Japanese here. Setting this parameter with a target language that does not support formality will fail, unless one of theprefer_...options are used. Possible options are:default(default)more- for a more formal languageless- for a more informal languageprefer_more- for a more formal language if available, otherwise fallback to default formalityprefer_less- for a more informal language if available, otherwise fallback to default formality
Values are
default,more,less,prefer_more, orprefer_less. Default value isdefault. -
A unique ID assigned to a glossary.
Responses
-
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.
-
Bad request. Please check error message and your parameters.
-
Authorization failed. Please supply a valid
DeepL-Auth-Keyvia theAuthorizationheader. -
The requested resource could not be found.
-
The request size exceeds the limit.
-
Too many requests. Please wait and resend your request.
-
Quota exceeded. The character limit has been reached.
-
Internal error.
-
Resource currently unavailable. Try again later.
-
Too many requests. Please wait and resend your request.
curl \
--request POST 'https://api.deepl.com/v2/document' \
--header "Authorization: $API_KEY" \
--header "Content-Type: multipart/form-data" \
--form "target_lang=DE" \
--form "file=@document.docx"{"target_lang" => "DE", "file" => "@document.docx"}{"source_lang" => "EN", "target_lang" => "DE", "file" => "@document.docx", "glossary_id" => "[yourGlossaryId]"}{
"document_id": "04DE5AD98A02647D83285A36021911C6",
"document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"
}