DeepL API

The DeepL API is accessible with a DeepL Pro subscription (DeepL API plan) . The API is an interface that allows other computer programs to send texts to our servers and receive high-quality translations. This opens a whole universe of opportunities for developers worldwide: Any translation product you can imagine can now be built on top of DeepL's superior translation technology.

A few examples:

Elegantly integrated, high-quality translations will become the new standard. We cannot wait to see the incredible products created by developers who share our vision of a more closely connected world in which language is no longer a barrier.


DeepL API — reference documentation (v2)

If you are a software developer, you can integrate DeepL’s technology into your website or app. The following is the technical documentation of DeepL’s JSON-based REST API. Please note, that

As of the current state, the two DeepL API versions differ only by the URL used to access the functionality.

Access to the DeepL Translator API

Use the DeepL Translator API to integrate the world's best translation technology.

The DeepL Translator API allows you to incorporate the DeepL Translator into your own products and services. Besides using it in your favourite CAT tools or integrating it into your intranet services, our API lends itself to many more of your in-house software applications.

The standardized programming interface makes integration into your own software extremely straightforward.

Your privacy and confidentiality are important to us - we don't save any texts sent to the DeepL Translator API, and we don't use them to improve the quality of the service.

Summary

The DeepL API is accessible through a REST interface. All functions support GET and POST methods, although POST requests are recommended. Request parameters are used to pass information to the API, results are returned in a JSON representation. Request parameters must be UTF-8 encoded. Authentication is based on fixed keys, SSL handling transport security.

The v2 API supports the translate and usage functions. See below for full documentation.

translate Function

The translate function is available at https://api.deepl.com/v2/translate. The call supports the following parameters:

ParameterDescription
textRequiredText to be translated. Only UTF8-encoded plain text is supported. The parameter may be specified multiple times and translations are returned in the same order as in the input. Each of the parameter values may contain multiple sentences.
source_langOptionalLanguage of the text to be translated. Can be one of the following
  • "EN"
  • "DE"
  • "FR"
  • "ES"
  • "PT"
  • "IT"
  • "NL"
  • "PL"
  • "RU"
If parameter is omitted, the API will detect the language of the text and translate it.
target_langRequiredThe language into which you want to translate. Can be one of the following
  • "EN"
  • "DE"
  • "FR"
  • "ES"
  • "PT"
  • "IT"
  • "NL"
  • "PL"
  • "RU"
tag_handlingOptionalSets which kind of tags should be handled. Comma-separated list of one or more of the following values:
  • "xml"
See section Tag handling below for more information.
non_splitting_tagsOptionalComma-separated list of XML tags which never split sentences. See section Tag handling below for more information.
ignore_tagsOptionalComma-separated list of XML tags whose content is never translated. See section Tag handling below for more information.
split_sentencesOptionalSets whether the translation engine should first split the input into sentences. This is enabled by default. Possible values are
  • "0"
  • "1" (default)
For applications which are sending one sentence per text parameter, it is advisable to set split_sentences=0, in order to prevent the engine from splitting the sentence unintentionally.
preserve_formattingOptionalSets whether the translation engine should preserve some aspects of the formatting, even if it would usually correct some aspects. Possible values are
  • "0" (default)
  • "1"
The formatting aspects controlled by the setting include:
  • punctuation at the beginning and end of the sentence,
  • upper/lower case at the beginning of the sentence.
auth_keyRequiredThe authentication key as provided to you.

Example Request

GET /v2/translate?text=Hallo%20Welt!&target_lang=EN&auth_key=123

Example Response

{
  "translations": [
    {
      "detected_source_language": "DE",
      "text": "Hello World!"
    }
  ]
}
     

Return value

The translate function returns a JSON representation of the translations in the order the text parameters have been specified.

Return valueDescription
detected_source_language The language which has been detected for the source text. It reflects the value of the source_lang parameter if it has been specified.
text The translated text.

Error handling

Errors are indicated by HTTP error codes. The following error codes are used:

CodeDescription
400Wrong request, please check error message and your parameters.
403Authorization failed. Please supply a valid auth_key parameter.
413Request Entity Too Large. The request size exceeds the current limit.
429Too many requests. Please wait and send your request once again.
456Quota exceeded. The character limit has been reached.

Additional information may be provided by a JSON response that contains more details about the error:

{
  "message": "Parameter 'target_lang' not specified."
}

XML Tag handling

By default the translation engine does not take tags into account. By setting the tag_handling parameter to xml, the API will process XML input by extracting sentences out of the structure, splitting into individual sentences, translating and placing back into the XML structure.

Generic example

The following example will guide you through how XML files are processed:

                <html>
<head>
    <title>A document's title</title>
</head>
<body>
    <div>This is the <b>first</b> sentence. Followed by a <i>second</i> one.</div>
    <div>This is the <span>third</span> sentence.</div>
</body>

The XML file is parsed and tags on the highest level which contain textual content other than whitespace are identified. In this case the title and the two div tags are found to contain text. The outer boundaries of these tags are considered to split sentences forcefully. Therefore each of the texts

is treated separately. The second text is furthermore split, as it contains two separate sentences. Each sentence is afterwards translated separately and tags within the sentence (used for formatting here) are applied to the matching words in the translated sentences.

Tuning which XML tags split sentences

In the case of some XML files, finding the highest-level tags with textual content and forcefully splitting sentence using these tags won't yield good results. The following example illustrates the issue

                <body>
    <div>This is the <b>first</b></div>   <div>sentence.</div>
</body>

In this case, the default behaviour of the API would be to split the text to be translated on the div tags. This causes This is the <b>first</b> and sentence. to be translated separately.

The behavior can be fine-tuned by setting the non_splitting_tags parameter to a value of div. This will instruct the XML engine to never split sentences on div tags and will cause the sentence This is the <b>first</b> sentence. to be translated in one piece.

Splitting on newlines

Please note that newlines will split sentences. So you should clean files like in the example, to not break sentences. In the following example the two parts of the sentence will be translated separately, even if div tags are not splitting

                <div>This is the <b>first</b></div>
<div>sentence.</div>

Placeholders

Tags which do not contain any content or are closed immediately (e.g. <br/>) are treated as placeholders. These are copied over to the translated sentences into a place which resembles their original location.

Ignored tags

Using the ignore_tags parameter, you can specify tags whose content is not translated. This is useful for tags enclosing variables or fixed names which you don't want to translate.

XML Tag handling is still in beta. Please check this page for updates in the future.

Limits

The request size should not exceed 30kbytes. The maximum number of texts to be translated within one request should not exceed 50.

Please ensure your client does not exceed the limits as specified in the quota documentation delivered to you. Your client should be prepared to back-off if you receive the HTTP response code 429 and retry the request later.

Authentication

When establishing the connection, you should verify that the the correct auth_key parameter has been provided using the API key provided. You should also verify whether the SSL certificate for api.deepl.com is valid.

usage Function

The usage function is available at https://api.deepl.com/v2/usage. The call supports the following parameters:

ParameterDescription
auth_keyRequiredThe authentication key as provided to you.

Example Request

GET /v2/usage?auth_key=123

Example Response

{
  "character_count": 180118,
  "character_limit": 1250000
}
     

Return value

The usage function returns a JSON representation of this billing period's character usage as well as the configured limit.

Return valueDescription
character_count Characters translated so far in the current billing period.
character_limit Total maximum volume of characters that can be translated in the current billing period.

Error handling

Errors are indicated by HTTP error codes. The following error codes are used:

CodeDescription
400Wrong request, please check error message and your parameters.
403Authorization failed. Please supply a valid auth_key parameter.

Authentication

When establishing the connection, you should verify that the the correct auth_key parameter has been provided using the API key provided. You should also verify whether the SSL certificate for api.deepl.com is valid.

API Access

site busy indicator