# Upload and Translate a Document **POST /v2/document** 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](https://www.deepl.com/docs-api/documents/get-document-status) and to [download the translated document](https://www.deepl.com/docs-api/documents/download-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](https://support.deepl.com/hc/articles/360020582359-Document-formats) 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. ## Servers - DeepL API Pro: https://api.deepl.com (DeepL API Pro) - DeepL API Free: https://api-free.deepl.com (DeepL API Free) ## Authentication methods - Auth header ## Parameters ### Body: multipart/form-data (object) - **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. **Note:** Some languages only work with `model_type` set to `quality_optimized`. See [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) for more details. - **target_lang** (string) The language into which the text should be translated. **Note:** Some languages only work with `model_type` set to `quality_optimized`. See [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) for more details. - **file** (string(binary)) 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 * `jpeg / jpg / png` - Image - **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. Note: Not all combinations of input file and translation file extensions are permitted. See [Document Format Conversions](https://www.deepl.com/docs-api/documents/format-conversions) for the permitted combinations. - **formality** (string) 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-BR` and `PT-PT` (Portuguese), `JA` (Japanese), and `RU` (Russian). Learn more about the plain/polite feature for Japanese [here](https://support.deepl.com/hc/en-us/articles/6306700061852-About-the-plain-polite-feature-in-Japanese). 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 - **glossary_id** (string) A unique ID assigned to a glossary. ## Responses ### 200 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. #### Headers - **X-Trace-ID** () A unique identifier for the request that can be included in bug reports to DeepL support. #### Body: application/json (object) - **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. - **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. ### 400 Bad request. Please check error message and your parameters. #### Headers - **X-Trace-ID** () A unique identifier for the request that can be included in bug reports to DeepL support. ### 403 Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header. #### Headers - **X-Trace-ID** () A unique identifier for the request that can be included in bug reports to DeepL support. ### 404 The requested resource could not be found. #### Headers - **X-Trace-ID** () A unique identifier for the request that can be included in bug reports to DeepL support. ### 413 The request size exceeds the limit. #### Headers - **X-Trace-ID** () A unique identifier for the request that can be included in bug reports to DeepL support. ### 429 Too many requests. Please wait and resend your request. #### Headers - **X-Trace-ID** () A unique identifier for the request that can be included in bug reports to DeepL support. ### 456 Quota exceeded. The character limit has been reached. #### Headers - **X-Trace-ID** () A unique identifier for the request that can be included in bug reports to DeepL support. ### 500 Internal error. #### Headers - **X-Trace-ID** () A unique identifier for the request that can be included in bug reports to DeepL support. ### 504 Resource currently unavailable. Try again later. #### Headers - **X-Trace-ID** () A unique identifier for the request that can be included in bug reports to DeepL support. ### 529 Too many requests. Please wait and resend your request. #### Headers - **X-Trace-ID** () A unique identifier for the request that can be included in bug reports to DeepL support. [Powered by Bump.sh](https://bump.sh)