> ## Documentation Index > Fetch the complete documentation index at: https://developers.deepl.com/llms.txt > Use this file to discover all available pages before exploring further. # Translate text ## OpenAPI ````yaml post /v2/translate openapi: 3.0.3 info: title: DeepL API Documentation description: >- The DeepL API provides programmatic access to DeepL’s language AI technology. Note: this OpenAPI spec is embedded into our API documentation and has shortened descriptions. termsOfService: https://www.deepl.com/pro-license contact: name: DeepL - Contact us url: https://www.deepl.com/contact-us version: 3.9.0 servers: - url: https://api.deepl.com description: DeepL API Pro - url: https://api-free.deepl.com description: DeepL API Free security: [] tags: - name: beta description: >- Experimental features that are under testing and not yet intended for production use. - name: TranslateText description: >- The text-translation API currently consists of a single endpoint, `translate`, which is described below. - name: TranslateDocuments description: >- The document translation API allows you to translate whole documents and supports the following file types and extensions: * `docx` - Microsoft Word Document * `pptx` - Microsoft PowerPoint Document * `xlsx` - Microsoft Excel Document * `pdf` - Portable Document Format * `htm / html` - HTML Document * `txt` - Plain Text Document * `xlf / xliff` - XLIFF Document, version 2.1 * `srt` - SRT Document * `jpeg` / `jpg` / `png` - Image (currently in beta) - name: RephraseText description: >- The `rephrase` endpoint is used to make corrections and adjustments to texts based on style or tone. - name: ManageMultilingualGlossaries description: >- The *glossary* functions allow you to create, inspect, edit and delete glossaries. Glossaries created with the glossary function can be used in translate requests by specifying the `glossary_id` parameter. A glossary contains (several) dictionaries. A dictionary is a mapping of source phrases to target phrases for a single language pair. If you encounter issues, please let us know at support@DeepL.com. Currently you can create glossaries with any of the languages DeepL supports (with the exception of Thai). The maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text, as well as the name of the glossary, is limited to 1024 UTF-8 bytes. A total of 1000 glossaries are allowed per account. When creating a dictionary with target language `EN`, `PT`, or `ZH`, it's not necessary to specify a variant (e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`). Dictionaries with target language `EN` can be used in translations with either English variant. Similarly `PT`, and `ZH` dictionaries can be used in translations with their corresponding variants. (When you provide the ID of a glossary to a translation, the appropriate dictionary is automatically applied. Currently glossaries can not yet be used with source language detection.) Glossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps. Please only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website. - name: ManageGlossaries description: >- Please note that this is the spec for the (old) v2 glossary endpoint. We recommend users switch to the newer v3 glossary endpoints, which support editability and multilinguality. The *glossary* functions allow you to create, inspect, and delete glossaries. Glossaries created with the glossary function can be used in translate requests by specifying the `glossary_id` parameter. If you encounter issues, please let us know at support@DeepL.com. Currently you can create glossaries with any of the languages DeepL supports (with the exception of Thai). - name: MetaInformation description: Information about API usage and value ranges - name: TranslationMemories description: >- The translation memory endpoints allow you to interact with your account's translation memories, used to store and reuse previously created translations. Translation memories can be used in text translation requests by specifying the `translation_memory_id` parameter to denote a specific translation memory and the `translation_memory_threshold` which defines the minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher). - name: VoiceAPI description: >- The Voice API provides real-time voice transcription and translation services. Use a two-step flow: first request a streaming URL via REST, then establish a WebSocket connection for streaming audio and receiving transcriptions. - name: VoiceTranslateJob description: >- **Alpha.** Async voice translation jobs. This API may change without notice. externalDocs: description: DeepL Pro - Plans and pricing url: https://www.deepl.com/pro#developer paths: /v2/translate: post: tags: - TranslateText summary: Request Translation operationId: translateText requestBody: required: true content: application/json: schema: type: object required: - text - target_lang properties: text: description: >- 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. type: array items: type: string example: Hello, World! source_lang: $ref: '#/components/schemas/SourceLanguage' target_lang: $ref: '#/components/schemas/TargetLanguage' context: $ref: '#/components/schemas/Context' show_billed_characters: $ref: '#/components/schemas/ShowBilledCharacters' split_sentences: $ref: '#/components/schemas/SplitSentencesOption' preserve_formatting: $ref: '#/components/schemas/PreserveFormattingOption' formality: $ref: '#/components/schemas/Formality' model_type: $ref: '#/components/schemas/ModelType' glossary_id: description: >- 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. type: string example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 style_id: description: >- Specify the [style rule list](/api-reference/style-rules) 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. type: string example: 7ff9bfd6-cd85-4190-8503-d6215a321519 translation_memory_id: $ref: '#/components/schemas/TranslationMemoryId' translation_memory_threshold: $ref: '#/components/schemas/TranslationMemoryThreshold' custom_instructions: description: >- 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. type: array items: type: string example: Use a friendly, diplomatic tone tag_handling: $ref: '#/components/schemas/TagHandlingOption' tag_handling_version: $ref: '#/components/schemas/TagHandlingVersionOption' outline_detection: $ref: '#/components/schemas/OutlineDetectionOption' enable_beta_languages: description: >- This parameter is maintained for backward compatibility and has no effect. type: boolean default: false deprecated: true non_splitting_tags: description: >- Comma-separated list of XML tags which never split sentences. type: array items: type: string example: non_splitting_tag splitting_tags: description: Comma-separated list of XML tags which always cause splits. type: array items: type: string example: splitting_tag ignore_tags: description: >- Comma-separated list of XML tags that indicate text not to be translated. type: array items: type: string example: ignore_tag application/x-www-form-urlencoded: schema: type: object required: - text - target_lang properties: text: description: >- 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. type: array items: type: string example: Hello, World! source_lang: $ref: '#/components/schemas/SourceLanguage' target_lang: $ref: '#/components/schemas/TargetLanguage' context: $ref: '#/components/schemas/Context' show_billed_characters: $ref: '#/components/schemas/ShowBilledCharacters' split_sentences: $ref: '#/components/schemas/SplitSentencesOption' preserve_formatting: $ref: '#/components/schemas/PreserveFormattingOptionStr' formality: $ref: '#/components/schemas/Formality' model_type: $ref: '#/components/schemas/ModelType' glossary_id: description: >- 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. type: string example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 translation_memory_id: $ref: '#/components/schemas/TranslationMemoryId' translation_memory_threshold: $ref: '#/components/schemas/TranslationMemoryThreshold' tag_handling: $ref: '#/components/schemas/TagHandlingOption' outline_detection: $ref: '#/components/schemas/OutlineDetectionOptionStr' enable_beta_languages: description: >- This parameter is maintained for backward compatibility and has no effect. type: boolean default: false deprecated: true non_splitting_tags: description: >- Comma-separated list of XML tags which never split sentences. type: array items: type: string example: non_splitting_tag splitting_tags: description: Comma-separated list of XML tags which always cause splits. type: array items: type: string example: splitting_tag ignore_tags: description: >- Comma-separated list of XML tags that indicate text not to be translated. type: array items: type: string example: ignore_tag encoding: text: style: form explode: true responses: '200': description: >- The translate function returns a JSON representation of the translations in the order the text parameters have been specified. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: type: object properties: translations: type: array minItems: 1 items: type: object properties: detected_source_language: description: >- The language detected in the source text. It reflects the value of the `source_lang` parameter, when specified. type: string example: EN text: description: The translated text. type: string example: Hallo, Welt! billed_characters: description: >- Number of characters counted by DeepL for billing purposes. Only present if the show_billed_characters parameter is set to true. type: integer example: 42 model_type_used: description: >- Indicates the translation model used. Only present if model_type parameter is included in the request. type: string example: quality_optimized '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/PayloadTooLarge' '414': $ref: '#/components/responses/URITooLong' '429': $ref: '#/components/responses/TooManyRequests' '456': $ref: '#/components/responses/QuotaExceeded' '500': $ref: '#/components/responses/InternalServerError' '504': $ref: '#/components/responses/ServiceUnavailable' '529': $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] components: schemas: SourceLanguage: type: string description: >- 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](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta). example: EN TargetLanguage: type: string description: >- The language into which the text should be translated. For the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta). example: DE Context: description: >- Additional context that can influence a translation but is not translated itself. Characters included in the `context` parameter will not be counted toward billing. type: string example: This is context. ShowBilledCharacters: description: >- 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. type: boolean SplitSentencesOption: description: >- 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 type: string enum: - '0' - '1' - nonewlines default: '1' example: '1' PreserveFormattingOption: description: >- Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects. type: boolean default: false Formality: description: >- 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 type: string enum: - default - more - less - prefer_more - prefer_less default: default example: prefer_more ModelType: type: string description: Specifies which DeepL model should be used for translation. enum: - quality_optimized - prefer_quality_optimized - latency_optimized TranslationMemoryId: type: string format: uuid description: >- 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 TranslationMemoryThreshold: type: integer description: >- The minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher). minimum: 0 maximum: 100 default: 75 example: 75 TagHandlingOption: description: |- Sets which kind of tags should be handled. Options currently available: * `xml` * `html` type: string enum: - xml - html example: html TagHandlingVersionOption: description: >- 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). type: string enum: - v2 - v1 OutlineDetectionOption: description: >- 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. type: boolean default: true PreserveFormattingOptionStr: description: >- Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects. type: string enum: - '0' - '1' default: '0' OutlineDetectionOptionStr: description: >- 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. type: string default: '1' enum: - '0' headers: X-Trace-ID: description: >- A unique identifier for the request that can be included in bug reports to DeepL support. schema: type: string example: 501c3d93cc0c4f11ae2f60a226c2f0f0 responses: BadRequest: description: Bad request. Please check error message and your parameters. Forbidden: description: >- Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header. NotFound: description: The requested resource could not be found. PayloadTooLarge: description: The request size exceeds the limit. URITooLong: description: >- The request URL is too long. You can avoid this error by using a POST request instead of a GET request, and sending the parameters in the HTTP body. TooManyRequests: description: Too many requests. Please wait and resend your request. QuotaExceeded: description: Quota exceeded. The character limit has been reached. InternalServerError: description: Internal error. ServiceUnavailable: description: Resource currently unavailable. Try again later. securitySchemes: auth_header: type: apiKey description: > Authentication with `Authorization` header and `DeepL-Auth-Key` authentication scheme. Example: `DeepL-Auth-Key ` name: Authorization in: header x-default: 'DeepL-Auth-Key ' ````