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.
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.
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.
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.
The translate function is available at https://api.deepl.com/v2/translate. The call supports the following parameters:
| Parameter | Description | |
|---|---|---|
| text | Required | Text 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_lang | Optional | Language of the text to be translated. Can be one of the following
|
| target_lang | Required | The language into which you want to translate. Can be one of the following
|
| tag_handling | Optional | Sets which kind of tags should be handled. Comma-separated list of one or more of the following values:
|
| non_splitting_tags | Optional | Comma-separated list of XML tags which never split sentences. See section Tag handling below for more information. |
| ignore_tags | Optional | Comma-separated list of XML tags whose content is never translated. See section Tag handling below for more information. |
| split_sentences | Optional | Sets whether the translation engine should first split the input into sentences. This is enabled
by default. Possible values are
|
| preserve_formatting | Optional | Sets whether the translation engine should preserve some aspects of the formatting, even if it would usually
correct some aspects. Possible values are
|
| auth_key | Required | The authentication key as provided to you. |
GET /v2/translate?text=Hallo%20Welt!&target_lang=EN&auth_key=123
{
"translations": [
{
"detected_source_language": "DE",
"text": "Hello World!"
}
]
}
The translate function returns a JSON representation of the translations in the order the text parameters have been specified.
| Return value | Description |
|---|---|
| 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. |
Errors are indicated by HTTP error codes. The following error codes are used:
| Code | Description |
|---|---|
| 400 | Wrong request, please check error message and your parameters. |
| 403 | Authorization failed. Please supply a valid auth_key parameter. |
| 413 | Request Entity Too Large. The request size exceeds the current limit. |
| 429 | Too many requests. Please wait and send your request once again. |
| 456 | Quota 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."
}
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.
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.
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.
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>
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.
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.
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.
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.
The usage function is available at https://api.deepl.com/v2/usage. The call supports the following parameters:
| Parameter | Description | |
|---|---|---|
| auth_key | Required | The authentication key as provided to you. |
GET /v2/usage?auth_key=123
{
"character_count": 180118,
"character_limit": 1250000
}
The usage function returns a JSON representation of this billing period's character usage as well as the configured limit.
| Return value | Description |
|---|---|
| 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. |
Errors are indicated by HTTP error codes. The following error codes are used:
| Code | Description |
|---|---|
| 400 | Wrong request, please check error message and your parameters. |
| 403 | Authorization failed. Please supply a valid auth_key parameter. |
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.
The DeepL API plan is specifically designed for software developers to build new software and applications on top of our translation technology. Please note that the DeepL API plan is the only plan that allows this. Also, the DeepL API plan does not allow you to use DeepL Pro within translation software.
The DeepL API plan offers you the option to set a limit on the number of characters that you can translate per month and thereby control your maximum costs. You need only activate Cost Control in your Account settings. Simply click "Change cost control settings," tick the checkbox to enable, and enter either the maximum number of characters or the maximum amount and apply the changes. You can make further changes at any time.
The Authentication Key is a code that enables DeepL Pro subscribers access to our API. The Authentication Key looks similar to “df4385c2-33de-e423-4134-ca1f7b3ea8b7”. You can find your unique Authentication Key in your DeepL Pro Account page.
You can use this form to generate sample URLs for the DeepL API. Simply enter the text you want to use and select the languages. The link changes automatically after every change. If you click on the generated link, you can see the result of the corresponding API call.