Se puede acceder a la API de DeepL mediante suscripción a DeepL Pro (plan DeepL API). La API es una interfaz que permite a otros programas informáticos enviar textos a nuestros servidores y recibir traducciones de gran calidad. Esto abre la puerta a un nuevo universo de oportunidades para los desarrolladores de todo el mundo: cualquier producto de traducción imaginable puede crearse ahora empleando la tecnología de traducción superior que ofrece DeepL.
Aquí van unos ejemplos:
Las traducciones de gran calidad e integradas con elegancia pasarán a ser el nuevo estándar. Estamos deseando descubrir los increíbles productos de todos los desarrolladores que compartan nuestra visión de un mundo donde las distancias se reduzcan y los idiomas dejen de ser una barrera.
Please note that:
Currently, the two DeepL API versions differ only in the URL used for access.
The DeepL API is accessible through a REST interface. Unless noted otherwise, 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 JSON. Request parameters must be UTF-8 encoded; results are also encoded in UTF-8. HTTP errors codes are used to signal errors. Authentication is based on fixed keys, and data transport is secured by SSL.
You can simulate and test various options in the live simulator.
You need an authentication key to access to the API. If you are logged in, the examples in this documentation will show your key. You can also find your key in your account settings. It is important to keep your key confidential. You should not put the key in Javascript code distributed publicly.
If your authentication key becomes compromised, you can recreate a new key and discard the old one in your account settings.
In all request methods the authentication key parameter is auth_key. The following example request to display usage information demonstrates how to set the authentication key parameter:
curl https://api.deepl.com/v2/usage?auth_key=
{
"character_count": 633586,
"character_limit": 1000000000000
}
GET /v2/usage?auth_key= HTTP/1.0
Host: api.deepl.com
User-Agent: YourApp
Accept: */*
{
"character_count": 633586,
"character_limit": 1000000000000
}
Errors are indicated by standard HTTP error codes. It is important to make sure that your application handles errors in an appropriate way. Special care should be taken to ensure proper handling of 429 and 456 errors.
The following error codes are used by the API:
| Code | Description |
|---|---|
| 400 | Bad request. Please check error message and your parameters. |
| 403 | Authorization failed. Please supply a valid auth_key parameter. |
| 404 | The requested resource could not be found. |
| 413 | The request size exceeds the limit. |
| 429 | Too many requests. Please wait and resend your request. |
| 456 | Quota exceeded. The character limit has been reached. |
| 503 | Resource currently unavailable. Try again later. |
| 5** | Internal error |
Additional information may be provided by a JSON response that contains more details about the error. In this case, this additional information will be contained in the message key.
curl "https://api.deepl.com/v2/translate?auth_key=&text=Translate it"
{
"message": "Parameter 'target_lang' not specified."
}
GET /v2/translate?auth_key=&text=Translate it HTTP/1.0
Host: api.deepl.com
User-Agent: YourApp
Accept: */*
{
"message": "Parameter 'target_lang' not specified."
}
The request size should not exceed 30kbytes.
In case of HTTP response code 429, your application should be configured to resend the request again later rather than constantly resending the request. If you're encountering 429 errors and would like to increase your translation speed, please contact support@DeepL.com
The translate function allows to translate texts and is available at https://api.deepl.com/v2/translate. This synchronous call supports the following basic 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 they are requested. Each of the parameter values may contain multiple sentences. Up to 50 texts can be sent for translation in one request. |
| source_lang | Optional | Language of the text to be translated. Options currently available:
|
| target_lang | Required | The language into which the text should be translated. Options currently available:
|
| 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 respect the original formatting, even if it would usually
correct some aspects. Possible values are:
|
| auth_key | Required | The authentication key as found in your account settings. |
The following extended parameters are also available. Please refer to the "Handling XML" section below for further information on how to use these parameters.
| Parameter | Description | |
|---|---|---|
| tag_handling | Optional | Sets which kind of tags should be handled. Options currently available:
|
| non_splitting_tags | Optional | Comma-separated list of XML tags which never split sentences. |
| outline_detection | Optional | Please see the "Handling XML" section for further details. |
| splitting_tags | Optional | Comma-separated list of XML tags which always cause splits. |
| ignore_tags | Optional | Comma-separated list of XML tags that indicate text not to be translated. |
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 detected in the source text. It reflects the value of the source_lang parameter, when specified. |
| text | The translated text. |
The following shows a basic request translating the text "Hello, world!"
curl https://api.deepl.com/v2/translate \
-d auth_key= \
-d "text=Hello, world" \
-d "target_lang=DE"
{
"translations": [
{"detected_source_language":"EN", "text":"Hallo, Welt"}
]
}
{
"translations": [
{"detected_source_language":"EN", "text":"Hallo, Welt"}
]
}
The translation function will (by default) try to split the text into sentences before translating. Splitting normally works on punctuation marks (e.g. "." or ";"), though you should not assume that every period will be handled as a sentence separator. This means that you can send multiple sentences as a value of the text parameter. The translation function will separate the sentences and return the whole translated paragraph, as shown in the example below:
curl https://api.deepl.com/v2/translate \
-d auth_key= \
-d "text=The table is green. The chair is black." \
-d "target_lang=DE"
{
"translations": [
{"detected_source_language":"EN", "text":"Der Tisch ist grün. Der Stuhl ist schwarz."}
]
}
In some cases, the sentence splitting functionality may cause issues by splitting sentences where there is actually only one sentence. This is especially the case if you're using special/uncommon character sequences which contain interpunctuation. In this case, you can disable sentence splitting altogether by setting the parameter split_sentences to 0. Please note that this will cause overlong sentences to be cut off, as the DeepL API cannot translate overly long sentences. In this case, you should split the sentences manually before submitting them for translation.
There are a few methods to translate larger volumes of text:
The following example illustrates how to send three texts to be translated at once:
curl https://api.deepl.com/v2/translate \
-d auth_key= \
-d "text=This is the first sentence." \
-d "text=This is the second sentence." \
-d "text=This is the third sentence." \
-d "target_lang=DE"
{
"translations": [
{"detected_source_language":"EN", "text":"Das ist der erste Satz."},
{"detected_source_language":"EN", "text":"Das ist der zweite Satz."},
{"detected_source_language":"EN", "text":"Dies ist der dritte Satz."}
]
}
POST /v2/translate?auth_key= HTTP/1.0
Host: api.deepl.com
User-Agent: YourApp
Accept: */*
Content-Length:
Content-Type: application/x-www-form-urlencoded
auth_key=&text=This is the first sentence.&text=This is the second sentence.&text=This is the third sentence.&target_lang=DE
{
"translations": [
{"detected_source_language":"EN","text":"Das ist der erste Satz."},
{"detected_source_language":"EN","text":"Das ist der zweite Satz."},
{"detected_source_language":"EN","text":"Dies ist der dritte Satz."}
]
}
You should take precaution with uncommon characters you may have embedded in your texts. Uncommon character sequences, which may be recognized markers within your system, might get translated or removed, resulting in a corrupted structure. In this case, it is advisable to either split the text so that there is no need to send markers, or to convert your markers to XML tags and enable XML handling (see the "Handling XML" section for more information).
The document function allows you to translate whole documents and is available at https://api.deepl.com/v2/document. This functionality is in beta. If you encounter issues, please let us know at support@DeepL.com. Please note that with every submitted document of type .pptx or .docx you are billed a minimum of 50'000 characters with the DeepL API plan, no matter how many characters are included in the document.
Because the request includes a file upload, it must be an HTTP POST request containing multipart/form-data. This call returns immediately after the document was uploaded and queued for translation. Further requests must be sent to the API to get updates on the translation progress or to download the translated document once the translation is finished (see other document request types below).
Once the document is fully uploaded, the translation starts immediately. Please be aware that the uploaded document is automatically removed from the server after the translation is done. You have to upload the document again in order to restart the translation.
The following parameters are supported:
| Parameter | Description | |
|---|---|---|
| source_lang | Optional | Language of the document to be translated. Options currently available:
|
| target_lang | Required | The language into which the document should be translated. Options currently available:
|
| auth_key | Required | The authentication key as found in your account settings. |
| file | Required | 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:
|
| filename | Optional | The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition. |
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.
| Return value | Description |
|---|---|
| document_id | 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 | 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. |
In the following example, a Microsoft Word document is uploaded and translated into German:
curl https://api.deepl.com/v2/document \
-F "file=@mydoc.docx" \
-F "auth_key=" \
-F "target_lang=DE"
{
"document_id": "4D93510B386BA64DC32102B88C17F018",
"document_key": "9AE7C976044834D6087EED9E82B3F86D38EF3C96DCC3D71CD50651A8B640E9A3"
}
POST /v2/document HTTP/1.0
Host: api.deepl.com
User-Agent: YourApp
Accept: */*
Content-Length:
Content-Type: multipart/form-data;boundary="boundary"
--boundary
Content-Disposition: form-data; name="file"; filename="mydoc.docx"
contents of your uploaded document
--boundary
Content-Disposition: form-data; name="auth_key"
--boundary
Content-Disposition: form-data; name="target_lang"
DE
--boundary--
{
"document_id": "4D93510B386BA64DC32102B88C17F018",
"document_key": "9AE7C976044834D6087EED9E82B3F86D38EF3C96DCC3D71CD50651A8B640E9A3"
}
The status of the document translation process can be checked by sending a status request to the document specific status URL https://api.deepl.com/v2/document/DOCUMENT_ID.
| Parameter | Description | |
|---|---|---|
| auth_key | Required | The authentication key as found in your account settings. |
| document_key | Required | The document encryption key that was sent to the client when the document was uploaded to the API. |
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.
| Return value | Description |
|---|---|
| document_id | 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 | A short description of the state the document translation process is currently in. Possible values are:
|
| seconds_remaining | Estimated number of seconds until the translation is done. This parameter is only included while the translation is ongoing. |
| billed_characters | The number of characters billed to your account. |
The following example shows a request asking for the current status of an ongoing document translation:
curl https://api.deepl.com/v2/document/4D93510B386BA64DC32102B88C17F018 \
-d auth_key= \
-d document_key=9AE7C976044834D6087EED9E82B3F86D38EF3C96DCC3D71CD50651A8B640E9A3
{
"document_id": "4D93510B386BA64DC32102B88C17F018 ",
"status":"translating", "seconds_remaining": 22
}
POST /v2/document/4D93510B386BA64DC32102B88C17F018 HTTP/1.0
Host: api.deepl.com
User-Agent: YourApp
Accept: */*
Content-Length:
Content-Type: application/x-www-form-urlencoded
auth_key=&document_key=9AE7C976044834D6087EED9E82B3F86D38EF3C96DCC3D71CD50651A8B640E9A3
{
"document_id": "4D93510B386BA64DC32102B88C17F018 ",
"status":"translating", "seconds_remaining": 22
}
Once the status of the document translation process is "done", the result can be downloaded from the document specific download URL https://api.deepl.com/v2/document/DOCUMENT_ID/result.
For privacy reasons the translated document is automatically removed from the server once it was downloaded and cannot be downloaded again.
| Parameter | Description | |
|---|---|---|
| auth_key | Required | The authentication key as found in your account settings. |
| document_key | Required | The document encryption key that was sent to the client when the document was uploaded to the API. |
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.
The following example shows how to download a translated document:
curl https://api.deepl.com/v2/document/4D93510B386BA64DC32102B88C17F018/result \
-d auth_key= \
-d document_key=9AE7C976044834D6087EED9E82B3F86D38EF3C96DCC3D71CD50651A8B640E9A3
binary document data
POST /v2/document/4D93510B386BA64DC32102B88C17F018/result HTTP/1.0
Host: api.deepl.com
User-Agent: YourApp
Accept: */*
Content-Length:
Content-Type: application/x-www-form-urlencoded
auth_key=&document_key=9AE7C976044834D6087EED9E82B3F86D38EF3C96DCC3D71CD50651A8B640E9A3
binary document data
Trying to download a document using a non-existing document ID or the wrong document key will result in a 404 error. As stated above, documents can only be downloaded once before they are deleted from the server and their document ID is invalidated.
A 503 result will be returned if the user tries to download a translated document that is currently being processed and is not yet ready for download. Please make sure to check that the document status is 'done' before trying to send a download request.
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 text out of the structure, splitting it into individual sentences, translating them, and placing them back into the XML structure.
We will look at the XML handling engine in the following cases:
If you want to translate text where individual parts are marked up, you can simply activate the XML engine by setting tag_handling to xml. The following examples show marked-up text and how it will be translated:
Press <i>Continue</i> to advance to the next page.
Drücken Sie <i>Weiter</i>, um zur nächsten Seite zu gelangen.
As the example shows, the tags are copied onto the translations corresponding to the original marked-up text. All types of XML tags are supported, including attributes:
<x id="17">Please welcome the participants</x> to today's meeting.
<x id="17">Bitte begrüßen Sie die Teilnehmer</x> des heutigen Treffens.
Nested tags are also supported:
The firm said it had been conducting an <a>internal <b>investigation</b></a> for several months.
Das Unternehmen sagte, dass es seit mehreren Monaten eine <a>interne <b>Untersuchung</b></a>durchgeführt habe.
A second important category are placeholder tags, which mark specific places in the text. Any tag that is immediately closed is considered a placeholder:
Artificial intelligence<a/> is already shaping our everyday<b></b> lives.
Künstliche Intelligenz<a/> prägt bereits heute unseren Alltag<b></b>.
In general, placeholders are associated with the words preceding or following them in the source sentence and are then applied to their respective translations in the target sentence.
With tag_handling enabled, the DeepL API is able to process structured XML content. This includes whole XML files, as the following example shows. Please note that for XML structured content, we set the parameter split_sentences to nonewlines to make sure that newlines do not alter the results. For better readability, the response is beautified for better readability.
<document>
<meta>
<title>A document's title</title>
</meta>
<content>
<par>This is the first sentence. Followed by a second one.</par>
<par>This is the third sentence.</par>
</content>
</document>
<document>
<meta>
<title>Der Titel eines Dokuments</title>
</meta>
<content>
<par>Das ist der erste Satz. Gefolgt von einem zweiten.</par>
<par>Dies ist der dritte Satz.</par>
</content>
</document>
Before sentences are translated, the XML file is parsed, and tags containing textual content other than whitespace are identified, in order to reproduce the XML structure in the translation.
In the example above, the title and the two par tags are found to contain text. These tags are considered sentence splitters. Therefore, each of the following three texts is treated separately:
The second text is further split, as it contains two separate sentences. Each sentence is then translated separately and tags within the sentences (used here for formatting) are applied to the corresponding words in the translation.
For some XML files, finding tags with textual content and splitting sentences using those tags won't yield the best results. The following example shows the engine splitting sentences on par tags and proceeding to translate the parts separately, resulting in an incorrect translation:
<par>The firm said it had been </par><par> conducting an internal investigation.</par>
<par>Die Firma sagte, es sei eine gute Idee gewesen.</par><par> Durchführung einer internen Untersuchung.</par>
As this can lead to bad translations, this type of structure should either be avoided, or the non_splitting_tags parameter should be set. The following example shows the same call, with the parameter:
<par>The firm said it had been </par><par> conducting an internal investigation.</par>
<par>Die Firma sagte, dass sie</par><par> eine interne Untersuchung durchgeführt</par><par> habe</par><par>.</par>
This time, the sentence is translated as a whole. The XML tags are now considered markup and copied into the translated sentence. As the translation of the words "had been" has moved to another position in the German sentence, the two par tags are duplicated (which is expected here).
The automatic detection of the XML structure won't yield best results in all XML files. You can disable this automatic mechanism altogether by setting the outline_detection parameter to 0 and selecting the tags that should be considered structure tags. This will split sentences using the splitting_tags parameter.
In the example below, we achieve the same results as the automatic engine by disabling automatic detection and setting the parameters manually:
<document>
<meta>
<title>A document's title</title>
</meta>
<content>
<par>This is the first sentence. Followed by a second one.</par>
<par>This is the third sentence.</par>
</content>
</document>
<document>
<meta>
<title>Der Titel eines Dokuments</title>
</meta>
<content>
<par>Das ist der erste Satz. Gefolgt von einem zweiten.</par>
<par>Dies ist der dritte Satz.</par>
</content>
</document>
While this approach is slightly more complicated, it allows for greater control over the structure of the translation output.
Please note that newlines will split sentences. You should therefore clean files to avoid breaking sentences as shown in the example below or set the parameter split_sentences to nonewlines. Here, the two parts of the sentence have been translated separately and this has caused an error: The word "the" has been incorrectly translated as "die" (the feminine definite article in German), though the German word for "sentence", "Satz", is masculine (der Satz).
<div>This is the first
sentence.</div>
<div>Dies ist die erste
Satz.</div>
To ensure that elements in the original text are not altered in translation (e.g. trademarks or product names), use the ignore_tags parameter and specify a tag for this function. In the following example, the ignore_tags parameter is set to x:
Please open the page <x>Settings</x> to configure your system.
Bitte öffnen Sie die Seite <x>Settings</x> um Ihr System zu konfigurieren.
The usage function is available at https://api.deepl.com/v2/usage and allows you to monitor how much you translate, as well as the limits set. The call supports the following parameters:
| Parameter | Description | |
|---|---|---|
| auth_key | Required | The authentication key as found in your account settings. |
The following example shows a usage request:
curl https://api.deepl.com/v2/usage \
-d auth_key=
{
"character_count": 180118,
"character_limit": 1250000
}
POST /v2/usage?auth_key= HTTP/1.0
Host: api.deepl.com
User-Agent: YourApp
Accept: */*
Content-Length:
Content-Type: application/x-www-form-urlencoded
auth_key=
{
"character_count": 180118,
"character_limit": 1250000
}
The usage function returns a JSON representation of the character usage within one billing period, as well as the set limit.
| Return value | Description |
|---|---|
| character_count | Characters translated so far in the current billing period. |
| character_limit | Current maximum number of characters that can be translated per billing period. |
The languages function is available at https://api.deepl.com/v2/languages and allows you to list all supported languages of the API. The call supports the following parameters:
| Parameter | Description | |
|---|---|---|
| auth_key | Required | The authentication key as found in your account settings. |
The following example shows a usage request:
curl https://api.deepl.com/v2/languages \
-d auth_key=
[
{
"language": "DE",
"name": "Deutsch"
},
{
"language": "EN",
"name": "English"
},
{
"language": "ES",
"name": "Español"
},
{
"language": "FR",
"name": "Français"
},
{
"language": "IT",
"name": "Italiano"
},
{
"language": "NL",
"name": "Nederlands"
},
{
"language": "PL",
"name": "Polski"
},
{
"language": "PT",
"name": "Português"
},
{
"language": "RU",
"name": "русский язык"
}
]
POST /v2/languages?auth_key= HTTP/1.0
Host: api.deepl.com
User-Agent: YourApp
Accept: */*
Content-Length:
Content-Type: application/x-www-form-urlencoded
auth_key=
[
{
"language": "DE",
"name": "Deutsch"
},
{
"language": "EN",
"name": "English"
},
{
"language": "ES",
"name": "Español"
},
{
"language": "FR",
"name": "Français"
},
{
"language": "IT",
"name": "Italiano"
},
{
"language": "NL",
"name": "Nederlands"
},
{
"language": "PL",
"name": "Polski"
},
{
"language": "PT",
"name": "Português"
},
{
"language": "RU",
"name": "русский язык"
}
]
The languages function returns a JSON representation of all currently supported languages. The response is an array where each item represents a supported language with the following values:
| Return value | Description |
|---|---|
| language | The language code of the given language. |
| name | Native name of the language. |
You can use this form to generate sample GET and POST requests for the DeepL API. Simply enter the text you would like to translate, and select the languages. The sample requests regenerate automatically after every change. To see the result of the corresponding API call, click Send.
URL for GET request
POST request
API response