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",
  "custom_instructions": [
    "Use a friendly, diplomatic tone"
  ],
  "tag_handling": "html",
  "tag_handling_version": "v1",
  "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 · 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.

target_lang · enum<string> · required

The language into which the text should be translated.

Note: Some languages only work with model_type set to quality_optimized. See supported languages for more details.

Available options: ACE, AF, AN, AR, AS, AY, AZ, BA, BE, BG, BHO, BN, BR, BS, CA, CEB, CKB, CS, CY, DA, DE, EL, EN, EO, ES, ET, EU, FA, FI, FR, GA, GL, GN, GOM, GU, HA, HE, HI, HR, HT, HU, HY, ID, IG, IS, IT, JA, JV, KA, KK, KMR, KO, KY, LA, LB, LMO, LN, LT, LV, MAI, MG, MI, MK, ML, MN, MR, MS, MT, MY, NB, NE, NL, OC, OM, PA, PAG, PAM, PL, PRS, PS, PT, QU, RO, RU, SA, SCN, SK, SL, SQ, SR, ST, SU, SV, SW, TA, TE, TG, TH, TK, TL, TN, TR, TS, TT, UK, UR, UZ, VI, WO, XH, YI, YUE, ZH, ZU

Example:

"DE"

source_lang · enum<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.

Note: Some languages only work with model_type set to quality_optimized. See supported languages for more details.

Available options: ACE, AF, AN, AR, AS, AY, AZ, BA, BE, BG, BHO, BN, BR, BS, CA, CEB, CKB, CS, CY, DA, DE, EL, EN, EO, ES, ET, EU, FA, FI, FR, GA, GL, GN, GOM, GU, HA, HE, HI, HR, HT, HU, HY, ID, IG, IS, IT, JA, JV, KA, KK, KMR, KO, KY, LA, LB, LMO, LN, LT, LV, MAI, MG, MI, MK, ML, MN, MR, MS, MT, MY, NB, NE, NL, OC, OM, PA, PAG, PAM, PL, PRS, PS, PT, QU, RO, RU, SA, SCN, SK, SL, SQ, SR, ST, SU, SV, SW, TA, TE, TG, TH, TK, TL, TN, TR, TS, TT, UK, UR, UZ, VI, WO, XH, YI, YUE, ZH, ZU

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"

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: v1, v2

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