OpenAPI spec for document translation

This page contains only a set of guides that is auto-generated from DeepL's OpenAPI file.

For a complete overview of document translation, including more detailed write-ups of request parameters, please see the Translate documents entry.

Upload and translate a document

Upload and Translate a Document

POSThttps://api.deepl.com/v2/document

Authorization

Body

source_langSourceLanguage (enum)

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.

BGCSDADEELENESETFIFRHUIDITJAKOLTLVNBNLPLPTRORUSKSLSVTRUKZH

target_lang*TargetLanguage (enum)

The language into which the text should be translated.

BGCSDADEELEN-GBEN-USESETFIFRHUIDITJAKOLTLVNBNLPLPT-BRPT-PTRORUSKSLSVTRUKZH

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

filenamestring

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_formatstring

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.

formalityFormality (enum)

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

defaultmorelessprefer_moreprefer_less

glossary_idGlossaryId (string)

A unique ID assigned to a glossary.

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.

Body

document_idstring

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_keystring

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.

Response

{
  "document_id": "04DE5AD98A02647D83285A36021911C6",
  "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"
}

Check document status

Check Document Status

POSThttps://api.deepl.com/v2/document/{document_id}

Authorization

Path parameters

document_id*string

The document ID that was sent to the client when the document was uploaded to the API.

Body

document_key*string

The document encryption key that was sent to the client when the document was uploaded to the API.

Response

The document status request returns a JSON object containing the document ID that was used in the request as well as string indicating the current status of the translation process. While the translation is running, the estimated number of seconds remaining until the process is done is also included in the response.

Body

document_id*string

A unique ID assigned to the uploaded document and the requested translation process. The same ID that was used when requesting the translation status.

status*enum

A short description of the state the document translation process is currently in. Possible values are:

queued - the translation job is waiting in line to be processed
translating - the translation is currently ongoing
done - the translation is done and the translated document is ready for download
error - an irrecoverable error occurred while translating the document

queuedtranslatingdoneerror

seconds_remaininginteger

Estimated number of seconds until the translation is done. This parameter is only included while status is "translating".

billed_charactersinteger

The number of characters billed to your account. The characters will only be billed after a successful download request.

error_messagestring

A short description of the error, if available. Note that the content is subject to change. This parameter may be included if an error occurred during translation.

Response

{
  "document_id": "04DE5AD98A02647D83285A36021911C6",
  "status": "done",
  "billed_characters": 1337,
  "error_message": "Only available if document status is error"
}

Download translated document

Download Translated Document

POSThttps://api.deepl.com/v2/document/{document_id}/result

Authorization

Path parameters

document_id*string

The document ID that was sent to the client when the document was uploaded to the API.

Body

document_key*string

The document encryption key that was sent to the client when the document was uploaded to the API.

Response

The document is provided as a download. There is no other data included in the response besides the document data. The content type used in the response corresponds to the document type.

Body

string (binary)

Response

"binary"

Dernière mise à jour il y a 1 mois