Translate text

Request Translation

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"
}
'

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

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

POST

translate

Request Translation

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"
}
'

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

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

{
  "message": "<string>",
  "code": "invalid_content_type"
}

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>

Headers

X-DeepL-Reporting-Tag

string

An optional custom reporting tag used to attribute this request's usage to a team, project, customer, or other category of your choosing. Values are limited to 100 characters. See How to use custom reporting tags for validation rules, naming guidance, and how to retrieve usage by tag.

Maximum string length: 100

Body

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.

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.

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. The glossary needs a dictionary for the language pair of the request.

If source_lang is omitted, DeepL detects the source language and uses the dictionary for the detected language pair. The request returns a 400 if the glossary has no dictionary for that pair.

Cannot be used together with glossary_ids.

Example:

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

glossary_ids

string[]

Specify up to 5 glossaries to use for the translation, as an array of glossary IDs. Each glossary's matching terms are applied to the translation.

Every listed glossary must contain a dictionary for the requested language pair.

If source_lang is omitted, DeepL detects the source language and every listed glossary must contain a dictionary for the detected language pair. A single glossary without a matching dictionary returns a 400 for the whole request.

Cannot be used together with glossary_id.

Maximum array length: 5

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. A list created for a root language (for example en) applies to that language and all of its variants (EN-GB, EN-US). A list created for a variant (for example en-GB) applies only when target_lang is that variant.

All model_type values are supported.

Example:

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

translation_memory_id

string<uuid>

A unique ID assigned to a translation memory.

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). A value below 50 is treated as 50.

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.

style_profile_id

string<uuid>

Translate with a style profile: its glossaries, style rule lists and translation memories through one ID. The profile is applied per text once the source language is known: the glossaries with a dictionary for the text's language pair, the style rule list for the target language, and the translation memories whose source language matches the text. A component that does not fit a text's language pair is left out for that text; this is not an error.

Cannot be combined with glossary_id, glossary_ids, style_id, translation_memory_id, translation_memory_threshold or custom_instructions. A request that combines them is rejected with 400 Bad Request. A style profile that does not exist or that your account cannot access is rejected with 404 Not Found.

Example:

"3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47"

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 (will become deprecated in the future).
v2: Improved algorithm released in October 2025. This is the default.

The tag_handling_version field in the response shows which version was applied.

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

deprecated

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

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

Translate

Customize

Voice

Languages

Admin

Authorizations

Headers

Body

Response