Translate text

POST /v2/translate

Request Translation

cURL

curl --request POST \
  --url https://api.deepl.com/v2/translate \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": [
    "Hello, World!"
  ],
  "target_lang": "DE",
  "source_lang": "EN",
  "context": "This is context.",
  "show_billed_characters": true,
  "split_sentences": "1",
  "preserve_formatting": false,
  "formality": "prefer_more",
  "model_type": "quality_optimized",
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "style_id": "7ff9bfd6-cd85-4190-8503-d6215a321519",
  "translation_memory_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
  "translation_memory_threshold": 75,
  "custom_instructions": [
    "Use a friendly, diplomatic tone"
  ],
  "tag_handling": "html",
  "tag_handling_version": "v2",
  "outline_detection": true,
  "enable_beta_languages": false,
  "non_splitting_tags": [
    "non_splitting_tag"
  ],
  "splitting_tags": [
    "splitting_tag"
  ],
  "ignore_tags": [
    "ignore_tag"
  ]
}
'

200

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Hallo, Welt!",
      "billed_characters": 42,
      "model_type_used": "quality_optimized"
    }
  ]
}

Authorizations

Authorization · string · header · default: DeepL-Auth-Key · required

Authentication with Authorization header and DeepL-Auth-Key authentication scheme. Example: DeepL-Auth-Key <api-key>

Body

application/jsonapplication/x-www-form-urlencoded

text · string[] · required

Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified many times in a single request, within the request size limit (128KiB). Translations are returned in the same order as they are requested. Each text in the array is translated independently — texts do not share context with each other.

target_lang · string · required

The language into which the text should be translated.

For the full list of supported target languages, see supported languages or query the GET /v3/languages endpoint (beta).

Example:

"DE"

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.

For the full list of supported source languages, see supported languages or query the GET /v3/languages endpoint (beta).

Example:

"EN"

context · string

Additional context that can influence a translation but is not translated itself.

Characters included in the context parameter will not be counted toward billing.

Example:

"This is context."

show_billed_characters · boolean

When true, the response will include the billed_characters parameter, giving the number of characters from the request that will be counted by DeepL for billing purposes.

split_sentences · enum<string> · default: 1

Sets whether the translation engine should first split the input into sentences.

Possible values are:

• 0 - no splitting at all, whole input is treated as one sentence
• 1 (default when tag_handling is not set to html) - splits on punctuation and on newlines
• nonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines

Available options: 0, 1, nonewlines

Example:

"1"

preserve_formatting · boolean · default: false

Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects.

formality · enum<string> · default: default

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

Available options: default, more, less, prefer_more, prefer_less

Example:

"prefer_more"

model_type · enum<string>

Specifies which DeepL model should be used for translation.

Available options: quality_optimized, prefer_quality_optimized, latency_optimized

glossary_id · string

Specify the glossary to use for the translation. Important: This requires the source_lang parameter to be set. The language pair of the glossary has to match the language pair of the request.

Example:

"def3a26b-3e84-45b3-84ae-0c0aaf3525f7"

style_id · string

Specify the style rule list to use for the translation.

Important: The target language has to match the language of the style rule list.

Note: Any request with the style_id parameter enabled will use quality_optimized models. Requests combining style_id and model_type: latency_optimized will be rejected.

Example:

"7ff9bfd6-cd85-4190-8503-d6215a321519"

translation_memory_id · string<uuid>

A unique ID assigned to a translation memory.

Note: Requests with the translation_memory_id parameter must use the quality_optimized model type. Requests combining translation_memory_id and model_type: latency_optimized will be rejected.

Example:

"a74d88fb-ed2a-4943-a664-a4512398b994"

translation_memory_threshold · integer · default: 75

The minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher).

Required range: 0 <= x <= 100

Example:

75

custom_instructions · string[]

Specify a list of instructions to customize the translation behavior. Up to 10 custom instructions can be specified, each with a maximum of 300 characters.

Important: The target language must be de, en, es, fr, it, ja, ko, zh or any variants of these languages.

Note: Any request with the custom_instructions parameter enabled will default to use the quality_optimized model type. Requests combining custom_instructions and model_type: latency_optimized will be rejected.

tag_handling · enum<string>

Sets which kind of tags should be handled. Options currently available:

• xml
• html

Available options: xml, html

Example:

"html"

tag_handling_version · enum<string>

Sets which version of the tag handling algorithm should be used. Options currently available:

• v1: Traditional algorithm (currently the default, will become deprecated in the future).
• v2: Improved algorithm released in October 2025 (will become the default in the future).

Available options: v2, v1

outline_detection · boolean · default: true

Disable the automatic detection of XML structure by setting the outline_detection parameter to false and selecting the tags that should be considered structure tags. This will split sentences using the splitting_tags parameter.

enable_beta_languages · boolean · default: false

No languages are currently in beta. This parameter is maintained for backward compatibility and has no effect.

non_splitting_tags · string[]

Comma-separated list of XML tags which never split sentences.

splitting_tags · string[]

Comma-separated list of XML tags which always cause splits.

ignore_tags · string[]

Comma-separated list of XML tags that indicate text not to be translated.

Response

200

application/json

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

translations · object[]

Minimum array length: 1

Show child attributes