# DeepL Documentation

> Developer documentation for the DeepL API: translate text and documents, transcribe and translate speech in real time, improve text, and customize output with glossaries, style rules, and translation memories.

> ## Agent Instructions
> Use the DeepL API when a task needs machine translation or text improvement, including translating text strings, whole documents with formatting preservation, or transcribing and translating live speech. Preferred terminology and phrasing may be enforced using customizations (glossaries, style rules, and translation memories). Retrieve supported languages for each product from the `/v3/languages` endpoints.
> Read the machine-readable API surface instead of inferring request shapes from prose: the REST spec is at https://developers.deepl.com/api-reference/openapi.yaml (also served as openapi.json) and the Voice WebSocket protocol is at https://developers.deepl.com/api-reference/voice/voice.asyncapi.yaml. These docs also expose an MCP server at https://developers.deepl.com/mcp (Streamable HTTP, no authentication).
> Use https://api.deepl.com for Pro plans and https://api-free.deepl.com for the Free plan. Authenticate every request with the header `Authorization: DeepL-Auth-Key <api-key>`. Never fabricate an API key: ask the user for one, or point them at https://developers.deepl.com/docs/getting-started/quickstart.
> Errors use standard HTTP status codes with a JSON body containing a `message` field, plus a `code` field where available, and an `X-Trace-ID` response header that identifies the request in DeepL's logs. Log `X-Trace-ID` by default. Retry 429 and 5xx with exponential backoff. Do not retry 456, which means the account quota is exhausted, or 400, which means the request itself is invalid.

# Get custom tag usage analytics
Source: https://developers.deepl.com/api-reference/admin-api/get-custom-tag-usage-analytics

get /v2/admin/analytics/custom-tags
Retrieve DeepL API usage broken down by custom tag for a date range, optionally aggregated by day, with paginated results.

## Date range

Specify the reporting window using the required `start_date` and `end_date` parameters in ISO 8601 date format (e.g., `2026-05-01`). The maximum date range is 366 days.

## Aggregation

The optional `aggregate_by` parameter controls how usage is grouped:

| **Value** | **Description** |
| :- | :- |
| `period` (default) | Returns total usage per custom tag over the entire date range |
| `day` | Returns usage per custom tag broken down by individual day |

Use `period` when you need a summary for billing or reporting. Use `day` when you need to analyze usage trends over time.

## Response structure

The response contains a `custom_tag_usage_report` object with the following fields:

| **Field** | **Description** |
| :- | :- |
| `aggregate_by` | The aggregation method used (`period` or `day`) |
| `start_date` | Start of the reporting period (ISO 8601 datetime) |
| `end_date` | End of the reporting period (ISO 8601 datetime) |
| `next_page` | Integer cursor for the next page of results. `null` if there are no further pages |
| `usage` | Array of usage entries, one per custom tag |

Each entry in `usage` includes:

* `custom_tag`: the tag identifier
* `usage_date`: the day the usage was recorded (ISO 8601 datetime). Only returned when `aggregate_by` is `day`
* `breakdown`: usage split by service type

### Usage breakdown

| **Field** | **Description** |
| :- | :- |
| `total_characters` | Combined character usage across character-based services |
| `text_translation_characters` | Characters used for text translation |
| `text_improvement_characters` | Characters used for text improvement (rephrasing) |
| `speech_to_text_minutes` | Minutes of speech-to-text usage. Fractional values are returned, for example `12.5` |
| `speech_to_speech_minutes` | Minutes of speech-to-speech usage. Fractional values are returned, for example `4.2` |

Voice usage is reported in minutes and is not included in `total_characters`, which covers character-based services only.

> [!WARNING]
>
> Custom tag data is recorded only for text translation and Voice API requests. Support for other request types will be added in a future update.

## Pagination

Results are paginated. If the response includes a non-null `next_page` value, pass it as the `page` parameter in your next request to retrieve the following page. Continue until `next_page` is `null`.


# Get usage analytics
Source: https://developers.deepl.com/api-reference/admin-api/get-usage-analytics

get /v2/admin/analytics
Retrieve organization-wide DeepL API usage for a date range, optionally grouped by API key or by API key and day.

## Date range

Specify the reporting window using the required `start_date` and `end_date` parameters. Both support the following formats (all in UTC):

| **Format** | **Example** |
| :- | :- |
| `YYYY-MM-DD` | `2025-09-29` |
| `YYYY-MM-DDTHH:MM:SS` | `2025-09-29T14:30:00` |

The maximum date range is 366 days.

## Grouping

The optional `group_by` parameter controls how results are organized:

| **Value** | **Description** |
| :- | :- |
| (default) | Returns total usage for the entire date range across all API keys |
| `key` | Groups usage by individual API key, showing totals for each key over the date range |
| `key_and_day` | Groups usage by both API key and day, providing daily breakdowns per key |

## Response structure

All responses include a breakdown of usage by service type:

| **Field** | **Description** |
| :- | :- |
| `total_characters` | Combined character usage across all services |
| `text_translation_characters` | Characters used for text translation |
| `document_translation_characters` | Characters used for document translation |
| `text_improvement_characters` | Characters used for text improvement (rephrasing) |
| `speech_to_text_minutes` | Duration of speech-to-text usage in minutes |


# Create a developer key
Source: https://developers.deepl.com/api-reference/admin-api/managing-developer-keys/create-key

post /v2/admin/developer-keys
Create a new DeepL API key for your organization as an admin, using the Admin API.



# Deactivate a developer key
Source: https://developers.deepl.com/api-reference/admin-api/managing-developer-keys/deactivate-key

put /v2/admin/developer-keys/deactivate
Deactivate a DeepL API key as an admin so it can no longer be used to authenticate requests.



# Get developer keys
Source: https://developers.deepl.com/api-reference/admin-api/managing-developer-keys/get-keys

get /v2/admin/developer-keys
List every DeepL API key in your organization as an admin, including each key's label and usage limits.



# Rename a developer key
Source: https://developers.deepl.com/api-reference/admin-api/managing-developer-keys/rename-key

put /v2/admin/developer-keys/label
Change the label on an existing DeepL API key as an admin, using the Admin API.



# Set developer key limits
Source: https://developers.deepl.com/api-reference/admin-api/managing-developer-keys/set-usage-limits

put /v2/admin/developer-keys/limits
Set or update the usage limit on an individual DeepL API key as an admin.



# Detect Language
Source: https://developers.deepl.com/api-reference/detect-language/detect-language-beta

Detect the language of text using DeepL's language detection service

> [!WARNING]
>
> **Beta Feature — Opt-in Required**
>
> The Detect Language API is currently in beta and requires explicit opt-in for your account. To request access, please [send a support request](https://support.deepl.com/hc/en-us/requests/new).

The Detect Language API allows you to identify the language of text content. This is a beta feature that requires special access permissions and is currently available only to select accounts.

## Best Practices

1. **Text Length**: Provide sufficient text for accurate detection. Very short texts may result in `insufficient_confidence` or `no_language_detected` status.

2. **Batch Processing**: You can detect multiple texts in a single request by providing an array of strings.

3. **Error Handling**: Check the `detection_status` field to understand the result. Only when `detection_status` is `success` will the `detected_language` field contain a valid language code.

4. **Rate Limiting**: Be mindful of API rate limits when making frequent requests.

## Feature Availability

This is a **beta feature** that requires:

* Account enrollment in the language detection beta program
* Compatible API key with appropriate permissions

Reach out to your DeepL contact to request access to the language detection API beta.

## Endpoint

```
POST /v3/detect/language
```

## Authentication

This endpoint requires authentication using the `DeepL-Auth-Key` header with a valid API key that has access to the language detection feature.

## Request Formats

**JSON Request**

```bash theme={null}
curl -X POST "https://api.deepl.com/v3/detect/language" \
  -H "Authorization: DeepL-Auth-Key YOUR_AUTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": [
      "Hello, how are you?",
      "Hola, ¿cómo estás?"
    ]
  }'
```

**Form-Encoded Request**

```bash theme={null}
curl -X POST "https://api.deepl.com/v3/detect/language" \
  -H "Authorization: DeepL-Auth-Key YOUR_AUTH_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "text=Hello, how are you?" \
  -d "text=Hola, ¿cómo estás?"
```

**HTTP Request**

```http theme={null}
POST /v3/detect/language HTTP/1.1
Host: api.deepl.com
Authorization: DeepL-Auth-Key YOUR_AUTH_KEY
Content-Type: application/json
Content-Length: 84

{
  "text": [
    "Hello, how are you?",
    "Hola, ¿cómo estás?"
  ]
}
```

### Request Parameters

**text** `string[]` *required*

List of text strings to detect languages for. Each string will be processed separately.

The response detections are returned in the same order as they are requested. Each of the parameter values may contain multiple sentences. Up to 50 texts can sent in one request.

## Response Format

**200 Success**

```json theme={null}
{
  "results": [
    {
      "detected_language": "en",
      "detection_status": "success"
    },
    {
      "detected_language": "es", 
      "detection_status": "success"
    }
  ]
}
```

Example responses for different detection statuses:

```json theme={null}
{
  "results": [
    {
      "detected_language": "en",
      "detection_status": "success"
    },
    {
      "detection_status": "insufficient_confidence"
    },
    {
      "detection_status": "unsupported_language"
    },
    {
      "detection_status": "no_language_detected"
    }
  ]
}
```

**400 Bad Request**

```json theme={null}
{
  "message": "Missing parameter text."
}
```

This error occurs when:

* The inputs in the request are malformed

**403 Forbidden**

```json theme={null}
{
  "message": "Forbidden"
}
```

This error occurs when:

* The API key doesn't have access to the language detection feature
* The account doesn't have the required permissions
* The feature flag is not enabled for the account

**415 Unsupported Media Type**

```json theme={null}
{
  "message": "Called with an unsupported media type. Supported media types: application/json or application/x-www-form-urlencoded. Please set the Content-Type header to a supported type."
}
```

This error occurs when:

* The request is in an unsupported format

**500 Internal Server Error**

```json theme={null}
{
  "message": "Internal server error."
}
```

This error occurs when there are issues with the internal language detection service.

### Response Fields

**results** `array` *required*

Array of detection results, one for each input text. Each result object contains a `detected_language` and a `detection_status` field.

**detected\_language** `string`

The detected language code when detection is successful.

**Language Codes** (when `detection_successful` is `true`):

* Standard BCP-47 language codes:  one of `"en"`, `"de"`, `"fr"`, `"es"`, `"pt"`, `"it"`, `"nl"`, `"pl"`, `"ru"`, `"zh"`, `"ja"`, `"bg"`, `"cs"`, `"da"`, `"el"`, `"et"`, `"fi"`, `"hu"`, `"lt"`, `"lv"`, `"ro"`, `"sk"`, `"sl"`, `"sv"`, `"tr"`, `"id"`, `"uk"`, `"ko"`, `"nb"`, `"ar"`, `"vi"`, `"he"`, `"th"`
* See [supported languages](/docs/getting-started/supported-languages) for more info

When `detection_status` is not `success`, this field is not defined.

**detection\_status** `string` *required*

Indicates the result of language detection. Possible values:

* `"success"` - Language successfully detected and returned in `detected_language`
* `"insufficient_confidence"` - Detection confidence too low to return a reliable single result
* `"unsupported_language"` - A language was detected but it's not supported by DeepL's translation service
* `"no_language_detected"` - No language could be detected from the input text

## Limitations

* Only supports detection of languages that are available in DeepL's translation service
* Requires high confidence to return the language
* Only returns the first top language guess for any single text, may not work well with language variants that are very similar to each other
* Limited to text-based detection (no support for document formats)


# Check document status
Source: https://developers.deepl.com/api-reference/document/check-document-status

post /v2/document/{document_id}
Check whether an uploaded document has finished translating, along with its billed character count and any error.



# Download translated document
Source: https://developers.deepl.com/api-reference/document/download-translated-document

post /v2/document/{document_id}/result
Download the translated file once a document translation job has finished. Results are available for a limited time.



# Upload and translate a document
Source: https://developers.deepl.com/api-reference/document/upload-and-translate-a-document

post /v2/document
Upload a document for translation and receive the document ID and key needed to check status and download the result.



# Create a glossary
Source: https://developers.deepl.com/api-reference/glossaries/create-a-glossary

post /v2/glossaries
Create a v2 glossary from a list of source and target term pairs for a single language pair.



# Delete a glossary
Source: https://developers.deepl.com/api-reference/glossaries/delete-a-glossary

delete /v2/glossaries/{glossary_id}
Delete a v2 glossary and all of its entries. Deleted glossaries cannot be recovered.



# List all glossaries
Source: https://developers.deepl.com/api-reference/glossaries/list-all-glossaries

get /v2/glossaries
List every v2 glossary on your account with its metadata, without returning the glossary entries.



# Retrieve glossary details
Source: https://developers.deepl.com/api-reference/glossaries/retrieve-glossary-details

get /v2/glossaries/{glossary_id}
Retrieve the metadata for a single v2 glossary, including its language pair and entry count, without the entries.



# Retrieve glossary entries
Source: https://developers.deepl.com/api-reference/glossaries/retrieve-glossary-entries

get /v2/glossaries/{glossary_id}/entries
Retrieve the term pairs stored in a single v2 glossary, in the format requested through the Accept header.



# Correct text
Source: https://developers.deepl.com/api-reference/improve-text/correct-text

post /v2/write/correct
Fixes spelling and grammar errors with minimal changes to wording.

The `/v2/write/correct` endpoint fixes spelling and grammar errors in one or more texts with minimal changes to wording, matching the "Corrections Only" mode in the DeepL Translator UI. It does not accept `writing_style` or `tone` and does not rephrase sentences for clarity. The broader [`/v2/write/rephrase`](/api-reference/improve-text/request-text-improvement) endpoint supports those parameters.


# Improve text
Source: https://developers.deepl.com/api-reference/improve-text/request-text-improvement

post /v2/write/rephrase
Improves text by correcting spelling and grammar and rewriting for a target writing style or tone.

The `/v2/write/rephrase` endpoint improves one or more texts by correcting spelling and grammar and rephrasing sentences for clarity. With the optional `writing_style` or `tone` parameters, the rewrite targets a specific style or tone. Its corrections-only counterpart, [`/v2/write/correct`](/api-reference/improve-text/correct-text), is limited to fixing mistakes with minimal changes to wording.


# Retrieve languages
Source: https://developers.deepl.com/api-reference/languages/retrieve-languages-by-resource

get /v3/languages
Retrieve the languages a DeepL API resource supports, including source and target roles and per-resource features.



# Retrieve language resources
Source: https://developers.deepl.com/api-reference/languages/retrieve-resources

get /v3/languages/resources
Learn how to retrieve the list of DeepL API resources and their supported language features.



# Retrieve supported languages (v2)
Source: https://developers.deepl.com/api-reference/languages/retrieve-supported-languages

get /v2/languages
Reference for the deprecated v2/languages endpoint. New integrations should use the v3/languages endpoints instead.

> [!WARNING]
>
> **`/v2/languages` is deprecated.** Use [`GET /v3/languages`](/docs/languages/using-the-languages-api) instead. See the [migration guide](/docs/languages/migrating-from-v2-languages) for details.
>
> We do not yet have a timeline for sunsetting /v2/languages, and we'll share more detail on this topic by the end of Q2 2026.


# Create a glossary
Source: https://developers.deepl.com/api-reference/multilingual-glossaries/create-a-glossary

post /v3/glossaries
Create a v3 multilingual glossary holding one or more dictionaries, each covering a source and target language pair.



# Delete a glossary
Source: https://developers.deepl.com/api-reference/multilingual-glossaries/delete-a-glossary

delete /v3/glossaries/{glossary_id}
Delete a v3 multilingual glossary along with all of its dictionaries and entries. This cannot be undone.



# Deletes the dictionary associated with the given language pair with the given glossary ID.
Source: https://developers.deepl.com/api-reference/multilingual-glossaries/deletes-the-dictionary-associated-with-the-given-language-pair-with-the-given-glossary-id

delete /v3/glossaries/{glossary_id}/dictionaries
Delete a single dictionary from a v3 multilingual glossary by its source and target language pair.



# Edit glossary details
Source: https://developers.deepl.com/api-reference/multilingual-glossaries/edit-glossary-details

patch /v3/glossaries/{glossary_id}
Rename a v3 multilingual glossary, or edit the dictionary for one source and target language pair.



# List all glossaries
Source: https://developers.deepl.com/api-reference/multilingual-glossaries/list-all-glossaries

get /v3/glossaries
List every v3 multilingual glossary on your account with its metadata, without returning the entries.



# List language pairs supported for glossaries
Source: https://developers.deepl.com/api-reference/multilingual-glossaries/list-language-pairs-supported-by-glossaries

get /v2/glossary-language-pairs
Reference for the deprecated v2/glossary-language-pairs endpoint. New integrations should use v3/languages instead.

> [!WARNING]
>
> **`/v2/glossary-language-pairs` is deprecated.** Use [`GET /v3/languages?resource=glossary`](/docs/languages/using-the-languages-api) instead. See the [migration guide](/docs/languages/migrating-from-v2-languages) for details.

> [!NOTE]
>
> This endpoint returns all possible language pairs for glossaries.
> [This list of supported languages](/docs/getting-started/supported-languages) may also be useful.


# Replaces or creates a dictionary in the glossary with the specified entries.
Source: https://developers.deepl.com/api-reference/multilingual-glossaries/replaces-or-creates-a-dictionary-in-the-glossary-with-the-specified-entries

put /v3/glossaries/{glossary_id}/dictionaries
Create a dictionary in a v3 multilingual glossary, or replace the entries in an existing one, for one language pair.



# Retrieve glossary details
Source: https://developers.deepl.com/api-reference/multilingual-glossaries/retrieve-glossary-details

get /v3/glossaries/{glossary_id}
Retrieve the metadata for a single v3 multilingual glossary, including its dictionaries, without the entries.



# Retrieve glossary entries
Source: https://developers.deepl.com/api-reference/multilingual-glossaries/retrieve-glossary-entries

get /v3/glossaries/{glossary_id}/entries
Retrieve the term pairs stored in a v3 multilingual glossary dictionary, returned in TSV format.



# Poll for the evaluation result
Source: https://developers.deepl.com/api-reference/quality-evaluations/poll

get /v1/quality-evaluations/{job_id}
Poll a document's quality evaluation for its status and retrieve the per-segment report of translation issues once it completes.

> [!WARNING]
>
> Quality evaluation is in [beta](/docs/resources/alpha-and-beta-features) and available to select DeepL customers only. To request access, contact your customer success manager.

Evaluations are requested with `enable_quality_evaluation` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document), which returns a `quality_evaluation_job_id`. That is the unique ID of the evaluation, and the value this endpoint takes. There is no public endpoint for starting an evaluation. For the end-to-end flow, see [Requesting a quality evaluation](/docs/best-practices/document-translations#requesting-a-quality-evaluation).

Evaluations resolve only within the account that requested them. A job ID belonging to another account returns `404`, the same response as an unknown ID.

## Status values

| **Value** | **HTTP status** | **Response body** |
| - | - | - |
| `processing` | `202` | `job_id` and `status` only. The `Retry-After` header carries the suggested number of seconds before the next poll. |
| `done` | `200` | The full report in `segments`. |
| `error` | `200` | An `error` object. The evaluation produced no report and will not produce one later. |

A completed evaluation and a failed one both return `200`, so `status` rather than the HTTP status code distinguishes them. A malformed `job_id` returns `400` without reaching an evaluation.

`error.code` is currently always `evaluation_failed`, so the response does not distinguish one cause of failure from another.

## Segment text

A report carries one entry in `segments` per evaluated segment of the document, in reading order, including segments where no issue was found. On those, `errors` is an empty array.

`segment_index` is that reading-order position. It is not a durable handle: re-translating the same document can produce a different segmentation.

`segment_score` rates the translation quality of that segment from 0 (lowest) to 100 (highest). It is always present in a completed report.

`source` and `target` hold the segment text as the evaluation read it, which is DeepL's own segmentation of the document with inline formatting tags removed. This text does not byte-match the text in the uploaded or translated file, and segment boundaries do not necessarily correspond to the paragraphs or sentences in the document. Span offsets index these two strings, not the uploaded or translated file.

Both fields are omitted when the text is unavailable for a segment. An issue on such a segment still carries its spans, but there is no text in the response to resolve them against.

`applied_glossary_term_pairs` lists the glossary term pairs applied to a segment when the document was translated. It is omitted for segments where no glossary term pair was applied. Each item gives the `source_term`, `target_term`, and the spans in `target` where the target term was applied.

## Span ranges

Each span describes a half-open interval over the segment's source or target text. `start` is the index of the first Unicode code point in the span; `end` is one past the last. The span covers the substring `text[start:end]` in Python-style slicing, and its length is `end - start`. For example:

```text theme={null}
target:   Unser Q3-Umsatz lag 5 % unter der Prognose.
```

A target span of `{ "start": 20, "end": 29 }` covers `target[20:29]`, the 9 code points `"5 % unter"`. Offsets count code points, not UTF-16 code units, so a language whose characters fall outside the Basic Multilingual Plane indexes differently than a UTF-16 string length would suggest.

* `source_spans` and `target_spans` are always present on an issue. If no span applies to that side, the value is an empty array
* Within a single issue, the ranges in `source_spans` (and in `target_spans`) are sorted by `start` and do not overlap
* Different issues may cover the same part of a segment
* `ranges` on an applied glossary term pair follows the same convention and indexes into `target`

## Severity values

The `severity` field on an issue takes one of three values.

| **Value** | **Description** |
| - | - |
| `Critical` | Renders the content unusable or significantly changes its meaning. For example, the meaning is reversed, important information is missing, or the content is unsuitable for the intended audience. |
| `Major` | Misleads the reader or significantly alters the meaning. The general idea is clear, but specific details are wrong, terminology is incorrect, or grammar issues make the text hard to understand. |
| `Minor` | Does not make the text unreadable, but can make it harder to understand and less appealing. |

## Type and sub-type values

Every issue carries a `type`, the top-level category, and a `sub_type`, which narrows it within that type. The five types and their sub-types are listed below.

> [!NOTE]
>
> New values for `type`, `sub_type`, and `severity` may be added without warning.

| **type** | **sub\_type** | **Description** |
| - | - | - |
| `Accuracy` | `Addition` | The target includes text that was not part of the source. |
| `Accuracy` | `Omission` | Content from the source is missing from the target. |
| `Accuracy` | `Mistranslation` | The content from the target doesn't match the content of the source. |
| `Accuracy` | `Over-translation` | The target is more specific than the source. |
| `Accuracy` | `Under-translation` | The target is less specific than the source. |
| `Accuracy` | `Untranslated text` | Content that should have been translated has been left untranslated. |
| `Fluency` | `Punctuation` | Punctuation is used incorrectly. |
| `Fluency` | `Spelling` | Incorrect spelling in the target text. |
| `Fluency` | `Grammar` | Issues with the grammar or syntax of the text, other than spelling and orthography. |
| `Fluency` | `Grammatical register` | The text uses the wrong grammatical register, such as informal forms where formal is required. |
| `Fluency` | `Inconsistency` | The text is not internally consistent. For example, using two different abbreviations for the same term. |
| `Fluency` | `Character encoding` | Characters are garbled due to incorrect application of an encoding. |
| `Style` | `Awkward` | The text is written in an awkward style. |
| `Style` | `Inconsistent style` | The text uses inconsistent stylistic conventions across sections. |
| `Miscellaneous` | Not enumerated | An error that does not fall into the other categories but is nonetheless clearly identifiable as a mistake. The sub-types of this type are not a fixed set, so read `sub_type` as free text. |
| `InternalTQEError` | `SegmentTooLarge` | The segment's source and target exceed 10,000 characters combined, so it was not analyzed. Reported with severity `Critical`. |

An issue of this type reports that a segment could not be evaluated rather than a defect in the translation. The rest of the document is evaluated normally.

## Supported language pairs

| **Source language** | **Target languages** |
| - | - |
| German (`DE`) | English (`EN-GB`, `EN-US`) |
| English (`EN`) | German (`DE`), Spanish (`ES`, `ES-419`), French (`FR`), Italian (`IT`), Japanese (`JA`), Korean (`KO`) |
| Spanish (`ES`) | English (`EN-GB`, `EN-US`) |
| French (`FR`) | English (`EN-GB`, `EN-US`) |
| Italian (`IT`) | English (`EN-GB`, `EN-US`) |
| Japanese (`JA`) | English (`EN-GB`, `EN-US`), Korean (`KO`), Chinese Simplified (`ZH-HANS`), Chinese Traditional (`ZH-HANT`) |
| Korean (`KO`) | English (`EN-GB`, `EN-US`), Japanese (`JA`) |
| Chinese (`ZH`) | Japanese (`JA`) |

Requesting an evaluation for a pair that is not listed is rejected with `400` when the document is uploaded, so an evaluation only ever exists for a supported pair. See [`enable_quality_evaluation`](/api-reference/document/upload-and-translate-a-document).

## Rate limit

This endpoint accepts 1,000 requests per minute per API key. Exceeding it returns `429 Too Many Requests`.

## Report retention

A report is retained for 24 hours after its evaluation reaches `done` or `error`. After that, this endpoint returns `404 Not Found` for that job ID.


# Create Spoken Terms collection
Source: https://developers.deepl.com/api-reference/spoken-terms/create-spoken-terms-collection

post /v3/spoken-terms
Create a new Spoken Terms collection with one or more term lists for voice transcription



# Delete Spoken Terms collection
Source: https://developers.deepl.com/api-reference/spoken-terms/delete-spoken-terms

delete /v3/spoken-terms/{spoken_terms_id}
Remove a Spoken Terms collection and all its term lists



# Delete a term list
Source: https://developers.deepl.com/api-reference/spoken-terms/delete-spoken-terms-list

delete /v3/spoken-terms/{spoken_terms_id}/term-lists
Remove a term list for a specific language from the Spoken Terms collection



# Edit Spoken Terms collection details
Source: https://developers.deepl.com/api-reference/spoken-terms/edit-spoken-terms-details

patch /v3/spoken-terms/{spoken_terms_id}
Update the collection name or merge new terms into an existing term list



# List all Spoken Terms collections
Source: https://developers.deepl.com/api-reference/spoken-terms/list-all-spoken-terms

get /v3/spoken-terms
Retrieve all Spoken Terms collections and their metadata



# Replace or create a term list
Source: https://developers.deepl.com/api-reference/spoken-terms/replace-or-create-term-list

put /v3/spoken-terms/{spoken_terms_id}/term-lists
Replace an existing term list for a language, or create a new one if it doesn't exist



# Retrieve Spoken Terms collection details
Source: https://developers.deepl.com/api-reference/spoken-terms/retrieve-spoken-terms-details

get /v3/spoken-terms/{spoken_terms_id}
Get metadata for a specific Spoken Terms collection, including term list information



# Retrieve Spoken Terms entries
Source: https://developers.deepl.com/api-reference/spoken-terms/retrieve-spoken-terms-entries

get /v3/spoken-terms/{spoken_terms_id}/entries
Get the actual terms for a specific language from a Spoken Terms collection



# Create a style profile
Source: https://developers.deepl.com/api-reference/style-profiles/create-style-profile

post /v3/style_profiles
Create a style profile that bundles glossaries, style rule lists and translation memories under one ID.



# Delete a style profile
Source: https://developers.deepl.com/api-reference/style-profiles/delete-style-profile

delete /v3/style_profiles/{style_profile_id}
Delete a style profile without deleting the components it links.



# Retrieve a style profile
Source: https://developers.deepl.com/api-reference/style-profiles/get-style-profile

get /v3/style_profiles/{style_profile_id}
Retrieve a style profile's linked components and metadata by its ID.



# List style profiles
Source: https://developers.deepl.com/api-reference/style-profiles/list-all-style-profiles

get /v3/style_profiles
Retrieve all style profiles available to your account, including the ones shared with it.



# Update a style profile
Source: https://developers.deepl.com/api-reference/style-profiles/update-style-profile

patch /v3/style_profiles/{style_profile_id}
Update a style profile's name, description, industry or linked components.



# Create a custom instruction
Source: https://developers.deepl.com/api-reference/style-rules/create-custom-instruction

post /v3/style_rules/{style_id}/custom_instructions
Add a custom instruction to a style rule list to shape translation output beyond the configured rules.



# Create a style rule list
Source: https://developers.deepl.com/api-reference/style-rules/create-style-rule

post /v3/style_rules
Create a style rule list, the container for the configured rules and custom instructions applied to translations.



# Delete a custom instruction
Source: https://developers.deepl.com/api-reference/style-rules/delete-custom-instruction

delete /v3/style_rules/{style_id}/custom_instructions/{instruction_id}
Remove a single custom instruction from a style rule list, leaving its configured rules in place.



# Delete a style rule list
Source: https://developers.deepl.com/api-reference/style-rules/delete-style-rule

delete /v3/style_rules/{style_id}
Delete a style rule list along with its configured rules and custom instructions.



# Get a custom instruction
Source: https://developers.deepl.com/api-reference/style-rules/get-custom-instruction

get /v3/style_rules/{style_id}/custom_instructions/{instruction_id}
Retrieve a single custom instruction from a style rule list by its instruction ID.



# Get a style rule list
Source: https://developers.deepl.com/api-reference/style-rules/get-style-rule

get /v3/style_rules/{style_id}
Retrieve a single style rule list, including its configured rules and custom instructions.



# Get all style rule lists
Source: https://developers.deepl.com/api-reference/style-rules/list-all-style-rules

get /v3/style_rules
List every style rule list on your account, with the configured rules and custom instructions on each.



# Replace configured rules
Source: https://developers.deepl.com/api-reference/style-rules/update-configured-rules

put /v3/style_rules/{style_id}/configured_rules
Replace the full set of configured rules on a style rule list. Rules left out of the request are removed.



# Replace a custom instruction
Source: https://developers.deepl.com/api-reference/style-rules/update-custom-instruction

put /v3/style_rules/{style_id}/custom_instructions/{instruction_id}
Replace the text of an existing custom instruction on a style rule list.



# Update a style rule list's name
Source: https://developers.deepl.com/api-reference/style-rules/update-style-rule

patch /v3/style_rules/{style_id}
Rename an existing style rule list without changing its configured rules or custom instructions.



# Translate text
Source: https://developers.deepl.com/api-reference/translate/request-translation

post /v2/translate
Translate text between any supported language pair, with options for formality, glossaries, tag handling, and context.



# Delete a translation memory
Source: https://developers.deepl.com/api-reference/translation-memory/delete-a-translation-memory

delete /v3/translation_memories/{translation_memory_id}
Learn how to permanently delete a translation memory and all of its segments.

Deletion is permanent and removes every segment in the translation memory. There is no recovery step and no trash to restore from. [Export the translation memory](/api-reference/translation-memory/export-a-translation-memory) first if you need a copy.

> [!WARNING]
>
> Translation requests that pass a deleted `translation_memory_id` fail. Update your integration to stop referencing the ID before you delete it, not after.

A successful delete returns `204 No Content` with an empty body, so check the status code rather than trying to parse a response.


# Export a translation memory
Source: https://developers.deepl.com/api-reference/translation-memory/export-a-translation-memory

post /v3/translation_memories/{translation_memory_id}/export
Learn how to export a translation memory as a TMX file, including how DeepL reuses recent exports and when it returns 409.

Exporting runs as a background job. This request starts the job and returns a `job_id`; the TMX file is downloaded separately once the job completes. TMX is currently the only export format, so there is no format parameter.

## Exporting a translation memory

**1. Start the export**

```bash theme={null}
curl -X POST "https://api.deepl.com/v3/translation_memories/a74d88fb-ed2a-4943-a664-a4512398b994/export" \
  -H "Authorization: DeepL-Auth-Key <yourAuthKey>"
```

```json theme={null}
{
  "job_id": "7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13",
  "parameters": {
    "translation_memory_id": "a74d88fb-ed2a-4943-a664-a4512398b994"
  }
}
```

**2. Poll the job and download the file**

Check [the job](/api-reference/translation-memory/retrieve-a-translation-memory-job) until `status` is `completed`, then download the file from `download_url` on the job result.

```bash theme={null}
curl -X GET "https://api.deepl.com/v3/translation_memories/jobs/7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13" \
  -H "Authorization: DeepL-Auth-Key <yourAuthKey>"
```

```json theme={null}
{
  "job_id": "7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13",
  "product": "translation_memory",
  "operation": "export",
  "creation_time": "2026-08-06T15:04:25.223Z",
  "updated_time": "2026-08-06T15:05:02.771Z",
  "parameters": {
    "translation_memory_id": "a74d88fb-ed2a-4943-a664-a4512398b994"
  },
  "results": [
    {
      "status": "completed",
      "download_url": "https://assets.deepl.com/download/7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13",
      "expires_at": "2026-08-06T16:05:02.771Z"
    }
  ]
}
```

## Handling 200, 202, and 409

The status code tells you whether a new job was started:

| **Status** | **Meaning** | **What to do** |
| - | - | - |
| `202 Accepted` | A new export job was started | Poll `job_id` |
| `200 OK` | A recent export was still available and was reused | Poll `job_id` |
| `409 Conflict` | An export of this translation memory is already running | Poll the job you already have; do not retry the export |

Treat `200` and `202` the same way. Both return a usable `job_id`, and the only difference is whether DeepL did the work again.

> [!WARNING]
>
> Do not retry on `409`. Retrying will keep conflicting with the in-progress export. Poll the `job_id` from your earlier request instead, and hold onto that ID so you can recover without a retry loop.

`download_url` is short-lived and stops working at `expires_at`. Download the file when the job completes rather than storing the URL for later. If the URL has expired, start a new export.


# Import a translation memory
Source: https://developers.deepl.com/api-reference/translation-memory/import-a-translation-memory

post /v3/translation_memories/import
Learn how to create a translation memory by declaring a TMX file, uploading it to a signed URL, and polling the import job.

This is how you create a translation memory: there is no endpoint that creates an empty one. Importing a TMX file creates the translation memory and fills it in a single job.

The request body describes the file you intend to upload; it does not carry the file. DeepL returns a signed `upload_url`, you upload the file to that URL, and processing starts automatically once the upload finishes.

## Importing a file

**1. Create the import job**

Send the file's name and size in bytes. The response returns the `job_id`, the `upload_url`, and the `expires_at` deadline for the upload.

```bash theme={null}
curl -X POST "https://api.deepl.com/v3/translation_memories/import" \
  -H "Authorization: DeepL-Auth-Key <yourAuthKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_file": {
      "file_name": "legal.tmx",
      "content_type": "application/xml",
      "content_length": 1024
    },
    "parameters": {
      "display_name": "Legal"
    }
  }'
```

```json theme={null}
{
  "job_id": "0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40",
  "upload_url": "https://assets.deepl.com/upload/0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40",
  "expires_at": "2026-08-06T15:34:25.223Z"
}
```

**2. Upload the TMX file**

`PUT` the file to `upload_url` before `expires_at`. The URL is already signed, so this request carries no DeepL credentials.

```bash theme={null}
curl -X PUT "https://assets.deepl.com/upload/0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40" \
  -H "Content-Type: application/xml" \
  --data-binary @legal.tmx
```

A successful upload returns no DeepL response body. Processing begins on its own, so there is no call to confirm the upload.

**3. Poll the job**

Check [the job](/api-reference/translation-memory/retrieve-a-translation-memory-job) until `status` is `completed` or `failed`.

```bash theme={null}
curl -X GET "https://api.deepl.com/v3/translation_memories/jobs/0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40" \
  -H "Authorization: DeepL-Auth-Key <yourAuthKey>"
```

On completion, the job result carries the `translation_memory_id` of the new translation memory.

```json theme={null}
{
  "job_id": "0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40",
  "product": "translation_memory",
  "operation": "import",
  "creation_time": "2026-08-06T15:04:25.223Z",
  "updated_time": "2026-08-06T15:06:11.418Z",
  "source_file": {
    "content_type": "application/xml",
    "content_length": 1024
  },
  "parameters": {
    "display_name": "Legal"
  },
  "results": [
    {
      "status": "completed",
      "translation_memory_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
      "skipped_segment_count": 12
    }
  ]
}
```

## Common mistakes

`content_length` must be greater than 0 and at most 1 GB. An oversize value is rejected as `400 Bad Request` with a message pointing at `source_file.content_length`.

`file_name` accepts at most 100 characters and `content_type` at most 127, both rejected as `400 Bad Request` if longer. TMX is the only supported format, so leave `content_type` unset or set it to `application/xml`.

A `202 Accepted` means the job exists, not that a translation memory does. Until the upload completes and the job reports `completed`, no translation memory has been created and there is no ID to reference.

If `expires_at` passes before you upload, the signed URL stops working. Create a new import job to get a fresh URL rather than retrying the old one.

A non-zero `skipped_segment_count` on a completed import is not a failure. Some segments were not stored, for example because they were malformed or duplicated an existing segment, but the rest imported normally. Check the value if you are reconciling segment counts against your source file.

If your account has reached its translation memory limit, the request returns `456`. Delete a translation memory before importing another.


# List translation memories
Source: https://developers.deepl.com/api-reference/translation-memory/list-translation-memories

get /v3/translation_memories
Retrieve the translation memories on your account, which store previously created translations for reuse.

To apply a translation memory to a translation request, see [Using translation memories](/docs/customize/using-translation-memories).


# List translation memory segments
Source: https://developers.deepl.com/api-reference/translation-memory/list-translation-memory-segments

get /v3/translation_memories/{translation_memory_id}/segments
Learn how to page through the source segments and translations stored in a translation memory using cursor-based pagination.

## Paginating with cursors

This endpoint pages with an opaque cursor, unlike [List translation memories](/api-reference/translation-memory/list-translation-memories), which uses numbered `page` values. Omit `page_cursor` on the first request, then pass each response's `next_page_cursor` to get the following page. A response with no `next_page_cursor` is the last page.

```bash theme={null}
# First page
curl -X GET "https://api.deepl.com/v3/translation_memories/a74d88fb-ed2a-4943-a664-a4512398b994/segments?page_size=50" \
  -H "Authorization: DeepL-Auth-Key <yourAuthKey>"

# Next page, using next_page_cursor from the response above
curl -X GET "https://api.deepl.com/v3/translation_memories/a74d88fb-ed2a-4943-a664-a4512398b994/segments?page_size=50&page_cursor=eyJvZmZzZXQiOjUwfQ" \
  -H "Authorization: DeepL-Auth-Key <yourAuthKey>"
```

Treat the cursor as opaque. Its format is not part of the API contract, so do not construct, decode, or increment it yourself. Cursors also encode the filter they were issued under: if you change `filter_text` or `filter_case_sensitive`, start again without a cursor.

> [!WARNING]
>
> `segment_count` is the total for the whole translation memory and is not reduced by `filter_text`. A filtered request still reports the full count, so do not use it to decide how many pages of filtered results to expect. Stop paginating when `next_page_cursor` is absent.

## Filtering

`filter_text` matches against both source text and every target translation, and must be at least 2 characters. Matching is case-insensitive unless you set `filter_case_sensitive=true`.


# Retrieve a translation memory
Source: https://developers.deepl.com/api-reference/translation-memory/retrieve-a-translation-memory

get /v3/translation_memories/{translation_memory_id}
Learn how to fetch a single translation memory's languages, segment count, and timestamps by its ID.

This returns the translation memory's metadata, not its contents. To read the stored segments, use [List translation memory segments](/api-reference/translation-memory/list-translation-memory-segments).

A translation memory that belongs to another account returns `404 Not Found` rather than `403 Forbidden`, so a 404 does not confirm that the ID is unused.


# Retrieve an import or export job
Source: https://developers.deepl.com/api-reference/translation-memory/retrieve-a-translation-memory-job

get /v3/translation_memories/jobs/{job_id}
Learn how to poll a translation memory import or export job and read its status values and results.

One endpoint covers both [import](/api-reference/translation-memory/import-a-translation-memory) and [export](/api-reference/translation-memory/export-a-translation-memory) jobs. Read `operation` to tell them apart, then read `results[0]` for the status and, once the job finishes, its output.

`results` always holds exactly one entry. It is an array so that jobs producing multiple outputs can be added later without a breaking change, so index into it rather than assuming a single object.

## Status values

| **Status** | **Applies to** | **Meaning** |
| - | - | - |
| `awaiting_input` | Import | The job exists but the file has not been uploaded yet. `status_metadata.required_action` says what is missing. |
| `processing` | Import, export | The file was received and is being processed. |
| `completed` | Import, export | The job succeeded. Read `translation_memory_id` (import) or `download_url` (export). |
| `failed` | Import, export | The job did not finish. `error.message` says why. |
| `expired` | Import, export | The job is too old to act on. Create a new one. |

Poll until the status is `completed`, `failed`, or `expired`. The other states are transient and will change on their own.

## Which fields to expect

Fields that do not apply to a job's `operation` are omitted rather than returned as `null`, so check for a field's presence before reading it:

* **Import jobs** include `source_file` and `parameters.display_name`. On completion, the result adds `translation_memory_id` and may add `skipped_segment_count`.
* **Export jobs** include `parameters.translation_memory_id`. On completion, the result adds `download_url` and `expires_at`.

> [!NOTE]
>
> An import that sits at `awaiting_input` means DeepL is still waiting for the file. Upload it to the `upload_url` from the import response; the status will not advance on its own.


# Check usage and limits
Source: https://developers.deepl.com/api-reference/usage-and-quota/check-usage-and-limits

get /v2/usage
Retrieve near-real-time character usage and account limits for the current billing period.

Returns usage within the current billing period together with the corresponding limits. Data is near-real-time: typically up to date within a few minutes of the usage being generated.

Response behavior the schema alone doesn't convey:

* For Pro API accounts, the response breaks usage down by product (`translate`, `write`) and reports both account totals and counts for the API key used to make the request. Responses for Free API and Pro Classic accounts contain only `character_count` and `character_limit`.
* `character_count` sums text translation, document translation, and text improvement characters. Characters are counted from the source text length in Unicode code points, so "A", "Δ", "あ", and "深" each count as one character.
* `character_limit` reflects a [Cost Control](/docs/best-practices/cost-control) limit if one is set; `api_key_character_limit` reflects a [key-level usage limit](/docs/admin/managing-api-keys#set-a-key-level-usage-limit) if one is set. Both fields return `1000000000000` when no limit is configured.

For usage data beyond the current billing period, or broken down by key or custom tag, see [Retrieving Usage Data](/docs/admin/retrieving-usage-data). For general API limitations, see [Usage limits](/docs/resources/usage-limits).


# Reconnect Session
Source: https://developers.deepl.com/api-reference/voice/reconnect-session

get /v3/voice/realtime
Reconnect to an interrupted real-time voice translation session and resume streaming audio.



# Request Session
Source: https://developers.deepl.com/api-reference/voice/request-session

post /v3/voice/realtime
Request a real-time voice translation session and receive the WebSocket streaming URL to connect to.



# WebSocket Streaming
Source: https://developers.deepl.com/api-reference/voice/websocket-streaming

AsyncAPI reference for the real-time voice WebSocket protocol, covering the messages sent in each direction.

> [!WARNING]
>
> Don't hardcode the WebSocket address shown on this page. Always connect to the `streaming_url` from the most recent [Request Session](/api-reference/voice/request-session) or [Reconnect Session](/api-reference/voice/reconnect-session) response, because it can change.


# Understanding API Key Permissions
Source: https://developers.deepl.com/docs/admin/api-key-permissions

Why scoped API keys exist, how DeepL enforces permission scopes, and when to choose a scoped key over an unrestricted one.

API key permissions let you limit what a developer API key can do. Instead of one key with full access to every endpoint, you can issue keys that are scoped to specific operations, for example a key that can only translate text or a key that can only read glossaries. Permissions are available on the API Pro, API Developer, API Growth, and API Enterprise plans, and currently apply only to developer keys; [admin keys](/docs/admin/managing-api-keys#manage-admin-api-keys) can't be scoped.

This page explains how the permissions model works. For the UI steps, see [Set key permissions](/docs/admin/managing-api-keys#set-key-permissions); for the full list of scopes, see [Permission Scopes](/docs/admin/permission-scopes).

## Permissions and scopes

Permissions are implemented as scopes. Each scope groups a set of related operations into a single capability you can grant to a key: `translate:text` covers text translation, `glossaries:read` covers reading glossaries, and so on. "Permissions" is the user-facing feature; "scopes" is the technical mechanism behind it.

## Why scoped keys

Before permissions were introduced in June 2026, every DeepL API key had full access to every endpoint. That's convenient, but it means a key embedded in a translation widget could also delete your glossaries, and a leaked key exposes your entire API surface.

Scoped keys apply the principle of least privilege: each key gets exactly the access its workload needs. A scoped key that leaks, or a service with a bug, can only do what its scopes allow.

| **Key type** | **Choose when** |
| - | - |
| Unrestricted | The key needs access to any endpoint and doesn't need to be limited |
| Scoped | The key should reach only specific endpoints, for example to prevent glossaries from being modified inadvertently |

## How enforcement works

A developer key becomes scoped the moment you assign it one or more scopes. Once scoped:

* The key can call only the endpoints fully covered by its scopes.
* Every other endpoint returns `403 Forbidden`, including endpoints that have no scope requirement of their own (currently the case for [audio file translation](/api-reference/jobs-voice-translate)).
* Some endpoints require more than one scope. The key must hold all of them; if any is missing, the request is denied.

When a scoped key calls an endpoint outside its scopes, the `message` field of the response lists what's missing:

```json theme={null}
{
  "message": "Missing required scope(s): glossaries:write. You can find more info in our docs: https://developers.deepl.com/docs/getting-started/auth"
}
```

Enforcement applies only to scoped keys. Unrestricted keys retain full access to every endpoint, and existing keys remain unrestricted until you assign them scopes. An account can hold any mix of scoped and unrestricted keys.


# Managing API Keys in the Account UI
Source: https://developers.deepl.com/docs/admin/managing-api-keys

Create, rename, deactivate, and set usage limits and permissions on DeepL API keys in the account UI.

Manage your API keys in the ["API Keys & Limits" tab](https://www.deepl.com/your-account/keys) when signed into your DeepL API account. A single subscription can have multiple simultaneously active keys: up to 25 on Pro API plans and up to 2 on Free API plans.

This tab has two subtabs: "API Keys" and "Admin API Keys." The sections below — filtering, creating, copying, renaming, deactivating, setting usage limits, and setting permissions — all describe the "API Keys" subtab. See [Manage admin API keys](#manage-admin-api-keys) for how the "Admin API Keys" subtab differs.

> [!NOTE]
>
> To create, deactivate, and limit developer keys programmatically instead, use the [Admin API](/docs/admin/overview#the-admin-api).

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/limits-and-api-keys-home.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=96d34779833aefa3b56dbdefe6847bf6)

The API Keys & Limits tab

## Filter API keys

You can filter API keys by dimensions such as key status, key-level permissions, and consumption. Use this to quickly narrow the key table down to, for example, only active keys or only keys nearing their usage limit.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/filter-api-keys.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=4b4550c82a2a577fa33437b14116a66b)

Filtering the API key table

## Create a key

Click "Create key". You can optionally name the key during creation; if you don't, it's named "DeepL API Key" automatically. Naming keys lets you find them later using the search bar on the "API keys" tab.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/create-api-key-dialog.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=249ab4de38272b0c50be0f5db2da96db)

Create a new API key

After you confirm, a popup shows the new key. Copy it from this popup to use it immediately, or copy it from the key table at any time.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/create-api-key-copy-modal.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=73c64b5a8fb001e61e6b2d76d345ed6c)

Copy an API key immediately after creating it

To create a key that can only access specific endpoints, select **Custom permissions** during creation. See [Set key permissions](#set-key-permissions).

## Copy a key

Click the "Copy" icon next to the key. For security reasons, the full key is never shown in the key table. Both active and deactivated keys can be copied.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/copy-api-key.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=b83f3e863f6f261c158dce3632cfcdc2)

Copy an API key

## Rename a key

Select "Rename key" from the key's options menu. Both active and deactivated keys can be renamed, and two keys can share the same name.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/rename-key.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=59fdcdf4e83af9a06d92e117aca63980)

Renaming a key

## Deactivate a key

> [!WARNING]
>
> A key stops working immediately when deactivated, and deactivation is permanent: a deactivated key cannot be reactivated.

Select "Deactivate key" from the key's options menu, then confirm.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/deactivate-key-step-1.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=96f967c487409b5f8e0b228d7382af7a)

Select "Deactivate key" from key options

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/deactivate-key-step-2.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=6d2c73d8c4c3a178022b3593aaa47eab)

Confirm deactivation of key

## Set a key-level usage limit

Key-level limits cap how much a key can consume in a one-month usage period. You can set a limit in characters (across text translation, document translation, and text improvement), STT minutes, or STS minutes. For example, a key with a 1,000,000 character limit stops consuming at 1,000,000 characters and starts fresh when the next usage period begins. You can see your current usage period dates in the [API Usage tab](https://www.deepl.com/your-account/usage).

To set a limit, select "Set limit" from the key's options menu, activate the limit, choose the unit (characters, STT minutes, or STS minutes), and enter an amount. Setting the limit to 0 prevents the key from consuming any of that unit.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/set-key-level-limit-1.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=33c3cd55ab7c90c7d917f820adf7689b)

Select "Set limit" from key options

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/set-key-level-limit-2.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=6cf1517bdde8808a777ae9d4df912487)

Activate and specify a limit

As with subscription-level [cost control](/docs/best-practices/cost-control):

* You receive notification emails when a key reaches 80% and 100% of its limit
* The API responds with `456 Quota exceeded` errors once 100% of the limit is reached

To monitor consumption against a limit, check the "Characters consumed" column in the key table or see [Retrieving Usage Data](/docs/admin/retrieving-usage-data).

## Set key permissions

Permissions restrict a developer key to specific endpoints. This section covers the UI steps; to understand how permissions are enforced, see [Understanding API Key Permissions](/docs/admin/api-key-permissions), and for what each scope covers, see [Permission Scopes](/docs/admin/permission-scopes).

To create a scoped key, click "Create key", select **Custom permissions**, choose one or more scopes from the list, and confirm.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/api-key-permissions-create.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=eb2894523cd13ab25197ebe28d2ab031)

Creating a scoped API key

To change permissions on an existing key, select "Edit permissions" from the key's options menu. Choose **All access** to make the key unrestricted, or **Custom permissions** to select specific scopes, then save.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/api-key-permissions-edit-dialog.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=cf7a4397fefef23a6aacd96dcc253b3d)

Choose all access or custom permissions

The "Permissions" column in the key table shows each key's status as a badge. Hover over a badge to see the assigned scopes.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/api-key-permissions-badge-hover.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=1613294881f4083047f61c80e4c0527f)

Hover a badge to view assigned scopes

## Manage admin API keys

On the API Pro, API Growth, and API Enterprise plans, you manage [admin keys](/docs/admin/overview#the-admin-api) on the "Admin API Keys" subtab of the ["API Keys & Limits" tab](https://www.deepl.com/your-account/keys?keyType=admin).

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/admin-api-tab.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=f2cd9d95961b3aa05551b2fe86d66268)

The Admin Keys subtab

Admin keys support the same actions as developer keys: create, copy, rename, and deactivate them from the "Admin API Keys" subtab exactly as described above. The differences:

* Admin keys always end with an `:adm` suffix, which distinguishes them from developer keys
* Unnamed admin keys are called "DeepL Admin Key" by default
* You can create up to 25 simultaneously active admin keys
* Usage limits and permissions don't apply to admin keys


# Admin
Source: https://developers.deepl.com/docs/admin/overview

Manage API keys, control what each key can access, and monitor usage across your organization, from the account UI or programmatically with the Admin API.

You can administer your DeepL API subscription in two ways:

* **Account UI**: the [API Keys & Limits](https://www.deepl.com/your-account/keys) and [API Usage](https://www.deepl.com/your-account/usage) tabs of your DeepL account, available on all plans
* **Admin API**: programmatic key management and usage analytics, for automating key provisioning, enforcing limits, and feeding usage data into your own dashboards or billing systems (see the [Admin API reference](/api-reference/admin-api/managing-developer-keys/create-key))

## The Admin API

The Admin API is available to all API Pro, API Growth, and API Enterprise subscribers.

The Admin API uses its own key type: admin keys, which always carry an `:adm` suffix to distinguish them from developer keys. You create admin keys in the ["Admin API Keys" subtab](https://www.deepl.com/your-account/keys?keyType=admin) of your account (see [Managing API Keys in the Account UI](/docs/admin/managing-api-keys#manage-admin-api-keys)) and pass them in the `Authorization` header of each request, just like developer keys:

`Authorization: DeepL-Auth-Key [yourAdminKey]`

Admin API endpoints are available on the Pro endpoint `https://api.deepl.com`. See the [Admin API reference](/api-reference/admin-api/managing-developer-keys/create-key) for request and response schemas.

## Start here

> **[Admin API Quickstart](/docs/admin/quickstart)**
>
> Create a developer key, cap its usage, and pull a usage report in four API calls.

> **[Managing API Keys in the Account UI](/docs/admin/managing-api-keys)**
>
> Create, rename, deactivate, and set usage limits on developer and admin keys in the account UI.

> **[Understanding API Key Permissions](/docs/admin/api-key-permissions)**
>
> Understand how permission scopes restrict what a developer key can do.

> **[Retrieving Usage Data](/docs/admin/retrieving-usage-data)**
>
> Pick the right usage data source and pull consumption data for your account, keys, or custom tags.

> **[Admin API Reference](/api-reference/admin-api/managing-developer-keys/create-key)**
>
> Endpoint reference for programmatic key management and usage analytics.


# Permission Scopes
Source: https://developers.deepl.com/docs/admin/permission-scopes

Every permission scope for DeepL developer API keys and the endpoints each scope covers.

Each scope grants a [scoped API key](/docs/admin/api-key-permissions) access to the endpoints listed under it. A scoped key can call only endpoints fully covered by its scopes; requests to any other endpoint return `403 Forbidden`.

> **Translate text (translate:text)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `POST` | [`/v2/translate`](/api-reference/translate/request-translation) |

> **Translate document (translate:document)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `POST` | [`/v2/document`](/api-reference/document/upload-and-translate-a-document) |
> | `GET` | [`/v2/document/{document_id}`](/api-reference/document/check-document-status) |
> | `GET` | [`/v2/document/{document_id}/result`](/api-reference/document/download-translated-document) |

> **Translate real-time speech (voice:realtime)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `POST` | [`/v3/voice/realtime`](/api-reference/voice/request-session) |
> | `GET` | [`/v3/voice/realtime`](/api-reference/voice/reconnect-session) |
>
> This scope also covers the [WebSocket stream](/api-reference/voice/websocket-streaming). You open the stream with the streaming URL and token from one of the endpoints above, so a scoped key needs `voice:realtime` to use any part of a real-time session.

> **Rephrase or correct text (write:improve)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `POST` | [`/v2/write/rephrase`](/api-reference/improve-text/request-text-improvement) |
> | `POST` | [`/v2/write/correct`](/api-reference/improve-text/correct-text) |

> **View glossaries and their entries (glossaries:read)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `GET` | [`/v3/glossaries`](/api-reference/multilingual-glossaries/list-all-glossaries) |
> | `GET` | [`/v3/glossaries/{glossary_id}`](/api-reference/multilingual-glossaries/retrieve-glossary-details) |
> | `GET` | [`/v3/glossaries/{glossary_id}/entries`](/api-reference/multilingual-glossaries/retrieve-glossary-entries) |
> | `GET` | [`/v2/glossaries`](/api-reference/glossaries/list-all-glossaries) |
> | `GET` | [`/v2/glossaries/{glossary_id}`](/api-reference/glossaries/retrieve-glossary-details) |
> | `GET` | [`/v2/glossaries/{glossary_id}/entries`](/api-reference/glossaries/retrieve-glossary-entries) |
> | `GET` | [`/v2/glossary-language-pairs`](/api-reference/multilingual-glossaries/list-language-pairs-supported-by-glossaries) |

> **Create, modify, and delete glossaries (glossaries:write)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `POST` | [`/v3/glossaries`](/api-reference/multilingual-glossaries/create-a-glossary) |
> | `PATCH` | [`/v3/glossaries/{glossary_id}`](/api-reference/multilingual-glossaries/edit-glossary-details) |
> | `PUT` | [`/v3/glossaries/{glossary_id}/dictionaries`](/api-reference/multilingual-glossaries/replaces-or-creates-a-dictionary-in-the-glossary-with-the-specified-entries) |
> | `DELETE` | [`/v3/glossaries/{glossary_id}`](/api-reference/multilingual-glossaries/delete-a-glossary) |
> | `DELETE` | [`/v3/glossaries/{glossary_id}/dictionaries`](/api-reference/multilingual-glossaries/deletes-the-dictionary-associated-with-the-given-language-pair-with-the-given-glossary-id) |
> | `POST` | [`/v2/glossaries`](/api-reference/glossaries/create-a-glossary) |
> | `DELETE` | [`/v2/glossaries/{glossary_id}`](/api-reference/glossaries/delete-a-glossary) |

> **View style rules and custom instructions (style\_rules:read)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `GET` | [`/v3/style_rules`](/api-reference/style-rules/list-all-style-rules) |
> | `GET` | [`/v3/style_rules/{style_id}`](/api-reference/style-rules/get-style-rule) |
> | `GET` | [`/v3/style_rules/{style_id}/custom_instructions/{instruction_id}`](/api-reference/style-rules/get-custom-instruction) |

> **Create, modify, and delete style rules and custom instructions (style\_rules:write)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `POST` | [`/v3/style_rules`](/api-reference/style-rules/create-style-rule) |
> | `PATCH` | [`/v3/style_rules/{style_id}`](/api-reference/style-rules/update-style-rule) |
> | `PUT` | [`/v3/style_rules/{style_id}/configured_rules`](/api-reference/style-rules/update-configured-rules) |
> | `DELETE` | [`/v3/style_rules/{style_id}`](/api-reference/style-rules/delete-style-rule) |
> | `POST` | [`/v3/style_rules/{style_id}/custom_instructions`](/api-reference/style-rules/create-custom-instruction) |
> | `PUT` | [`/v3/style_rules/{style_id}/custom_instructions/{instruction_id}`](/api-reference/style-rules/update-custom-instruction) |
> | `DELETE` | [`/v3/style_rules/{style_id}/custom_instructions/{instruction_id}`](/api-reference/style-rules/delete-custom-instruction) |

> **Retrieve and export translation memories (translation\_memories:read)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `GET` | [`/v3/translation_memories`](/api-reference/translation-memory/list-translation-memories) |
> | `GET` | [`/v3/translation_memories/{translation_memory_id}`](/api-reference/translation-memory/retrieve-a-translation-memory) |
> | `GET` | [`/v3/translation_memories/{translation_memory_id}/segments`](/api-reference/translation-memory/list-translation-memory-segments) |
> | `POST` | [`/v3/translation_memories/{translation_memory_id}/export`](/api-reference/translation-memory/export-a-translation-memory) |
> | `GET` | [`/v3/translation_memories/jobs/{job_id}`](/api-reference/translation-memory/retrieve-a-translation-memory-job) |
>
> Exporting is a read operation, so it needs `translation_memories:read` rather than `translation_memories:write`, even though it uses `POST`.

> **Import and delete translation memories (translation\_memories:write)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `POST` | [`/v3/translation_memories/import`](/api-reference/translation-memory/import-a-translation-memory) |
> | `DELETE` | [`/v3/translation_memories/{translation_memory_id}`](/api-reference/translation-memory/delete-a-translation-memory) |

> **Retrieve languages and resources (languages:read)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `GET` | [`/v3/languages`](/api-reference/languages/retrieve-languages-by-resource) |
> | `GET` | [`/v3/languages/resources`](/api-reference/languages/retrieve-resources) |
> | `GET` | [`/v2/languages`](/api-reference/languages/retrieve-supported-languages) |

> **View subscription usage and limits (usage:read)**
>
> | **Method** | **Endpoint** |
> | - | - |
> | `GET` | [`/v2/usage`](/api-reference/usage-and-quota/check-usage-and-limits) |

> [!NOTE]
>
> No scope covers [audio file translation](/api-reference/jobs-voice-translate) yet, so those endpoints are accessible only with unrestricted keys.


# Admin API Quickstart
Source: https://developers.deepl.com/docs/admin/quickstart

Create a developer API key, set a usage limit on it, and pull a per-key usage report in four calls to the Admin API.

In this tutorial, we'll use the Admin API to provision a new developer API key for a team, set a character limit to control costs, and then retrieve a usage report to confirm activity. By the end, you'll have made four API calls that cover the core Admin API workflow.

## What you'll learn

* How to create a developer API key programmatically
* How to apply a character usage limit to a key
* How to retrieve an organization-wide usage report broken down by key
* What the response objects look like at each step

## Prerequisites

* An API Pro, API Growth, or API Enterprise subscription (see [The Admin API](/docs/admin/overview#the-admin-api))
* An [**admin API key**](/docs/admin/managing-api-keys#manage-admin-api-keys) for your DeepL organization. Regular developer keys cannot access Admin API endpoints.
* `curl` installed on your machine

> [!TIP]
>
> Responses in this tutorial are shown formatted. To pretty-print JSON in your terminal, install [jq](https://jqlang.org/) and pipe curl output through it: `curl ... | jq`

## Building with an AI coding agent?

Wire it up to the [DeepL Docs MCP Server](/docs/getting-started/docs-mcp-server) so it can search and read this documentation while it writes code. In Claude Code:

```bash theme={null}
claude mcp add --transport http deepl-docs https://developers.deepl.com/mcp
```

Then describe what you want to build. To get the same result as this tutorial, paste:

```text wrap theme={null}
Using the DeepL Admin API, write a script that creates a developer API key labeled "Staging Team Key", sets a 500,000 character usage limit on it, and then displays a per-key usage report for the last month.
```

## Step 1: List existing developer keys

Before creating a new key, let's see what's already in the organization. This gives us a baseline and confirms that authentication is working.

```bash theme={null}
curl https://api.deepl.com/v2/admin/developer-keys \
  -H "Authorization: DeepL-Auth-Key YOUR_ADMIN_KEY"
```

You'll receive an array with one object per developer key, active and deactivated:

```json theme={null}
[
  {
    "key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890:1f2e3d4c-5b6a-7980-dcba-0987654321fe",
    "label": "Production API Key",
    "creation_time": "2026-05-12T09:41:03.512Z",
    "deactivated_time": null,
    "is_deactivated": false,
    "usage_limits": {
      "characters": null,
      "speech_to_text_milliseconds": null,
      "speech_to_speech_milliseconds": null
    }
  }
]
```

Notice the `key_id` field, composed of two GUIDs separated by a `:` symbol. You'll use it to target specific keys in later steps. `null` usage limits mean no cap is set on that key.

If you get a `403 Forbidden` response here, double-check that you're using an admin key with an `:adm` suffix, not a developer key.

## Step 2: Create a new developer key

Now let's create a key for a new team or service. We'll give it a descriptive label so it's easy to identify later.

```bash theme={null}
curl https://api.deepl.com/v2/admin/developer-keys \
  -H "Authorization: DeepL-Auth-Key YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Staging Team Key"}'
```

The response returns the newly created key object:

```json theme={null}
{
  "key_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210:0a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "label": "Staging Team Key",
  "creation_time": "2026-07-09T10:02:47.118Z",
  "deactivated_time": null,
  "is_deactivated": false,
  "usage_limits": {
    "characters": null,
    "speech_to_text_milliseconds": null,
    "speech_to_speech_milliseconds": null
  }
}
```

Copy the `key_id` from this response. You'll need it in the next step.

## Step 3: Set a character usage limit

By default, a new key has no usage cap. Let's set a character limit so the staging key can't consume more quota than intended.

Replace `KEY_ID` with the `key_id` from the previous step.

```bash theme={null}
curl https://api.deepl.com/v2/admin/developer-keys/limits \
  -X PUT \
  -H "Authorization: DeepL-Auth-Key YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": "KEY_ID",
    "characters": 500000
  }'
```

The response returns the updated key object. Confirm that `usage_limits.characters` now shows `500000`:

```json theme={null}
{
  "key_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210:0a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "label": "Staging Team Key",
  "creation_time": "2026-07-09T10:02:47.118Z",
  "deactivated_time": null,
  "is_deactivated": false,
  "usage_limits": {
    "characters": 500000,
    "speech_to_text_milliseconds": null,
    "speech_to_speech_milliseconds": null
  }
}
```

Once the key reaches its character limit, requests using it return `456 Quota exceeded` errors until the next usage period starts or you raise the limit.

## Step 4: Pull a usage report by key

After the team has started using the key, let's retrieve a usage report to see how much quota each key has consumed. We'll group the results by API key so we can see per-key totals.

Replace the dates with a range that covers the period you want to inspect. Date ranges can span up to 366 days, and data is available up to and including the previous UTC calendar day.

```bash theme={null}
curl "https://api.deepl.com/v2/admin/analytics?start_date=2026-06-01&end_date=2026-07-01&group_by=key" \
  -H "Authorization: DeepL-Auth-Key YOUR_ADMIN_KEY"
```

The response includes a `usage_report` object with per-key breakdowns and an organization-wide total:

```json theme={null}
{
  "usage_report": {
    "start_date": "2026-06-01T00:00:00",
    "end_date": "2026-07-01T00:00:00",
    "group_by": "key",
    "key_usages": [
      {
        "api_key": "f9e8****6789",
        "api_key_label": "Staging Team Key",
        "usage": {
          "text_translation_characters": 4892,
          "text_improvement_characters": 4727,
          "document_translation_characters": 0,
          "speech_to_text_minutes": 107.46,
          "total_characters": 9619
        }
      }
    ],
    "total_usage": {
      "text_translation_characters": 4892,
      "text_improvement_characters": 4727,
      "document_translation_characters": 0,
      "speech_to_text_minutes": 107.46,
      "total_characters": 9619
    }
  }
}
```

Notice that `api_key` values are partially masked in the response for security. You can match keys to their labels using the `api_key_label` field.

You have now created a key, capped its usage, and confirmed activity through the analytics endpoint.

## What's next

* **Rename or reorganize keys**: Use the [rename endpoint](/api-reference/admin-api/managing-developer-keys/rename-key) to update a key's label as teams or services change.
* **Deactivate a key**: When a key is no longer needed, [deactivate it](/api-reference/admin-api/managing-developer-keys/deactivate-key). Deactivation is permanent, but deactivated keys remain visible in your key list.
* **Daily usage breakdowns**: Change `group_by` to `key_and_day` to see per-key usage broken down by day, which is useful for spotting spikes.
* **Custom tag analytics**: If you annotate API requests with custom tags, use the [custom tag analytics endpoint](/api-reference/admin-api/get-custom-tag-usage-analytics) to break down usage by tag.
* **Other data sources**: See [Retrieving Usage Data](/docs/admin/retrieving-usage-data) for a comparison of all the ways to monitor your DeepL API usage.


# Retrieving Usage Data
Source: https://developers.deepl.com/docs/admin/retrieving-usage-data

Compare DeepL's usage data sources and pull character and minute consumption for your account, API keys, or custom tags.

DeepL offers several ways to retrieve usage data so you can track character and minute consumption and the associated costs. This guide compares the available data sources and shows how to use each one.

> [!NOTE]
>
> Consumption data in the account UI, in CSV exports, and in the [Admin API analytics endpoints](/api-reference/admin-api/get-usage-analytics) is available up to and including the previous UTC calendar day. For near-real-time data, use the [`/usage` endpoint](/api-reference/usage-and-quota/check-usage-and-limits).

## Choose a data source

| **Data source** | **Scope** | **Time range** | **Data freshness** | **Interface** |
| - | - | - | - | - |
| [API Keys & Limits tab](#api-keys-and-limits-tab) | Per API key | Current usage period only | Previous UTC day | Account UI |
| [API Usage tab](#api-usage-tab) | Account total (plus year-to-date on yearly plans) | Current usage period (and yearly period) | Previous UTC day | Account UI |
| [CSV export](#csv-export) | Per API key, per custom tag, per language pair, or per document | Preset ranges for all reports; custom ranges up to 4 months and optional grouping by day for key-level and tag-level reports | Previous UTC day | CSV download |
| [`/usage` endpoint](#the-usage-endpoint) | Account total | Current usage period only | Near-real-time (within minutes) | REST API |
| [Admin API analytics](#admin-api-analytics) | Per API key or per custom tag | Custom date range, optional grouping by day | Previous UTC day | REST API |

Use the **account UI** for a quick check while signed in, the **CSV export** for detailed or offline analysis per key, per custom tag, per language pair, or per document, the **`/usage` endpoint** for programmatic near-real-time quota checks, and the **Admin API analytics endpoints** for programmatic reporting and cost attribution.

## API Keys and Limits tab

To check per-key consumption for the current monthly usage period, open the [API Keys & Limits tab](https://www.deepl.com/your-account/keys). It shows consumption for each API key in a single unit at a time — characters, speech-to-text (STT) minutes, or speech-to-speech (STS) minutes.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/api-keys-and-limits-with-usage.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=46f99154b47d44f470708abaf2351b67)

The API Keys & Limits tab

Use the unit dropdown above the key table to switch which usage unit the table displays.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/api-keys-and-limits-with-usage-unit-dropdown.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=c8ab84605e386a10463fd97b08f0b865)

Switching the displayed usage unit

## API Usage tab

To check your account totals, open the [API Usage tab](https://www.deepl.com/your-account/usage). It shows total character and STT minute usage for the current monthly usage period, and if you're on a yearly plan, usage to date for your yearly billing period, too.

![](https://mintcdn.com/deepl-c950b784/G4w6sAcpHNkksvKb/_assets/images/api-growth-annual-usage-tab.png?fit=max\&auto=format\&n=G4w6sAcpHNkksvKb\&q=85\&s=01cd3997908131a0b7f97d2f4d3802fa)

The API Usage tab

## CSV export

Generate a CSV report of your usage for a chosen time period. Four report types are available:

* **API key-level report**: characters translated per API key, including a column that breaks out text improvement (Write API) characters separately. Key-level usage is not broken out on invoices; retrieve it via CSV export, the "API Keys & Limits" tab, or the [Admin API analytics endpoints](#admin-api-analytics).
* **Custom tag-level report**: characters translated per [custom reporting tag](/docs/learning-how-tos/examples-and-guides/how-to-use-custom-reporting-tags). Only tagged requests appear in this report, so results reflect a subset of total usage unless every request is tagged.
* **Language pair-level report**: characters translated per source-target language pair. Generally available on the API Enterprise plan. On the API Pro plan, it's available on request; contact your customer success manager to enable it.
* **Document translation report**: one row per translated document, with the document type, language pair, input characters, billed characters (reflecting any [billing minimum](/docs/best-practices/document-translations#billing-minimums) applied), and whether a glossary was used. Use it to trace document translation usage back to individual documents. Generally available on the API Enterprise plan. On the API Pro plan, it's available on request; contact your customer success manager to enable it.

To download a report, click "Download CSV usage report" on the [API Keys & Limits tab](https://www.deepl.com/your-account/keys) or the [API Usage tab](https://www.deepl.com/your-account/usage) and select "API key-level report," "Custom tag-level report," "Language pair-level report," or "Document translation report" from the dropdown. Then select a time period and click "Download your report".

![](https://mintcdn.com/deepl-c950b784/tcrlYvr_Q3YiDP74/_assets/images/download-csv-usage-report.png?fit=max\&auto=format\&n=tcrlYvr_Q3YiDP74\&q=85\&s=123aa3484501c7961e8791354104810c)

Select a report type from the "Download CSV usage report" dropdown

Select one of the presets or, for the API key-level and custom tag-level reports, a custom date range of up to 4 months (on UTC calendar days). The language pair-level and document translation reports currently support presets only.

For the API key-level and custom tag-level reports, presets cover rolling windows from the last 24 hours up to the last year, as well as calendar months and usage periods. The language pair-level and document translation reports offer these presets:

* Last 24 hours
* Last 7 days
* Last 30 days
* Current month
* Last month
* Current usage period
* Last usage period

Rolling presets include the current day; calendar-month and usage-period ranges align to UTC day or period boundaries, so they might not start and end on a full calendar day.

In the API key-level and custom tag-level reports, you can also group usage data by UTC calendar day for any time range. The language pair-level and document translation reports currently don't support grouping by day.

![](https://mintcdn.com/deepl-c950b784/5Ui5bPgQu6CdkNqe/_assets/images/group-by-day-option.png?fit=max\&auto=format\&n=5Ui5bPgQu6CdkNqe\&q=85\&s=f0836efccbec267aaa40b4888e29ffc4)

Select the "Group by day" option to group usage data by UTC calendar day

> [!NOTE]
>
> Document translation data is only included in reports with a time period starting on or after May 16, 2024 00:00 UTC. Text translation data is included for all time periods.

## The usage endpoint

The [`/usage` endpoint](/api-reference/usage-and-quota/check-usage-and-limits) returns a near-real-time snapshot of character and minute usage in the current monthly usage period, typically up to date within a few minutes of the usage being generated. Use it for programmatic quota checks, for example before submitting a large translation batch.

## Admin API analytics

The [Admin API](/docs/admin/overview#the-admin-api) provides programmatic access to usage data over a custom date range, with optional grouping by day. It requires an [admin key](/docs/admin/managing-api-keys#manage-admin-api-keys) for authentication. Two endpoints are available:

* [Get usage analytics](/api-reference/admin-api/get-usage-analytics) returns usage statistics across all services (text translation, document translation, text improvement, and speech-to-text), in total or grouped by API key
* [Get custom tag usage analytics](/api-reference/admin-api/get-custom-tag-usage-analytics) returns usage broken down by custom tag

Custom tags are an optional dimension for cost attribution: attach a tag to individual API requests with the `X-DeepL-Reporting-Tag` header to track consumption by team, project, or any other category. Only tagged requests appear in custom-tag analytics, so results reflect a subset of total usage unless every request is tagged. See [How to use custom reporting tags](/docs/learning-how-tos/examples-and-guides/how-to-use-custom-reporting-tags) for setup and naming guidance. If you prefer a download over an API call, the same per-tag data is available as a [custom tag-level CSV export](#csv-export).

For a worked example of pulling analytics data into a dashboard, see the [usage analytics dashboard cookbook](/docs/learning-how-tos/cookbook/usage-analytics-dashboard).


# CORS requests
Source: https://developers.deepl.com/docs/best-practices/cors-requests

Why the DeepL API rejects requests sent directly from a browser, and how to call it from your backend instead.

If you try to send requests to the DeepL API from the browser, your requests will fail with the [HTTP 403 Forbidden status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403) with a message stating “blocked by CORS policy”. The DeepL API does not allow calls directly from browser-based applications.

Requests to third-party APIs from front-end applications would expose your credentials on the web, leaving your account vulnerable to fraud and abuse. You should never reveal your API authentication key in publicly accessible code.

If you realize your API authentication key has been compromised, log in to your DeepL account immediately. Under "Account Details", you have the option to deactivate any of your active API keys. Deactivate any compromised key to prevent others from using it with the DeepL API. You can also generate new keys from the same page.

To safely use the DeepL API on your website or application, you can route your requests through your own backend servers. This keeps your credentials hidden and allows you to specify CORS policies and rate limits as required by your use case.

DeepL's official open-source [client libraries](/docs/getting-started/client-libraries) can help you create these backend implementations. For prototyping and frontend testing, you can use the [DeepL API Node.js Proxy](https://github.com/DeepL/deepl-api-nodejs-proxy/), a lightweight ready-to-use proxy server that handles CORS and keeps your API key secure.


# Subscription-level cost control
Source: https://developers.deepl.com/docs/best-practices/cost-control

Set a subscription-wide limit on characters, STT minutes, or STS minutes to cap your maximum costs.

As a DeepL API Pro user, you have the option to set a limit on the amount of characters, STT minutes, or STS minutes consumed across your entire subscription per month, limiting your maximum costs. You activate "Cost Control" on the ["API Usage" tab](https://www.deepl.com/your-account/usage), the central hub for usage and cost settings. This limit applies subscription-wide; for a limit on a single key instead, see [Set a key-level usage limit](/docs/admin/managing-api-keys#set-a-key-level-usage-limit).

## Set a cost control limit

1. Navigate to the ["API Usage" tab](https://www.deepl.com/your-account/usage)
2. Click to change cost control settings for the relevant unit — a separate link manages the limit for each of characters, STT minutes, and STS minutes
3. Check the box to activate the limit
4. Enter the maximum consumption per month
5. Click "Submit" to save the changes

Your new cost control limit is applied immediately.

![](https://mintcdn.com/deepl-c950b784/V62dEoFj_Y8TzBkJ/_assets/images/subscription-level-cost-control.png?fit=max\&auto=format\&n=V62dEoFj_Y8TzBkJ\&q=85\&s=4bce05df078f738e714f3808d949cd1f)

Per-unit links for managing subscription-level cost control

Once you reach your limit, DeepL stops processing further translation requests until the end of the usage period, to avoid exceeding your set maximum cost. If you want to translate more, you can change the cost control limit at any time.

Within the characters unit, the limit is enforced against the sum of Translate API and Write API characters; it's not possible to set separate limits for each. Characters, STT minutes, and STS minutes each have their own independent limit.

## FAQ

#### I have been notified that my Cost Control was raised, but I didn't raise it. What should I do?

Every time your "Cost Control" limit is raised, you receive a notification email for security reasons. If you receive such a notification but did not raise your "Cost Control" limit, we highly suggest you reset your authentication key and the password to your DeepL Pro account as soon as possible.


# Document translations
Source: https://developers.deepl.com/docs/best-practices/document-translations

Handle file size limits, status codes, quality evaluation reports, and error details when translating documents with the DeepL API.

Below you will find general guidance on how to handle status codes and error details to ensure a smooth document translation experience.

### Document File Size Limits

We impose [size limits](/docs/resources/usage-limits) per file type. Limits vary by format and API plan.
For DOCX and PPTX, our .NET, PHP and NodeJS client libraries offer functionality to minify files by temporarily extracting large media formats before sending them to the DeepL API. Stripped media are reinserted after document translation is completed.

This allows users to translate files that might hit the size limit.

### Billing minimums

Every submitted document of type `.pptx`, `.docx`, `.doc`, `.xlsx`, or `.pdf` is billed a minimum of 50,000 characters on DeepL API plans, no matter how many characters the document contains. Formats currently in beta are not billed and are not subject to this minimum.

### One source/target language pair per upload

The `source_lang` and `target_lang` values on the request apply to the entire uploaded file. For most formats, keep each upload to a single source language for consistent results — behavior on content that isn't in the selected source language is not guaranteed.

**XLIFF** is the exception: `<source>` elements are translated as independent segments, so XLIFF files containing segments in different languages are handled segment-by-segment. Note: the per-`<file>` `source-language` attribute inside an XLIFF is ignored — DeepL uses the request's `source_lang` value for every segment.

All content in the uploaded file counts toward billed characters, including content that was not actually translated.

### Same-language source and target are rejected

Requests where the source and target languages are equal — including regional variants of the same language, e.g. `EN` → `EN-US` or `EN-US` → `EN-GB` — are rejected with HTTP 400 (`Source and target language are equal.`). To adapt regional spelling, post-process the translated output yourself.

### Format-specific gotchas

Each supported format has behaviors and constraints worth knowing before you upload. The most common surprises:

**XML**

* Only text between element tags is translated. Attribute values and processing instructions are left alone.
* XML `<!-- comments -->` may be picked up as translatable text and their delimiters escaped in the output — strip comments before uploading if downstream tooling relies on them.
* `CDATA` section content **is** translated — the markers are stripped and the inner text is sent to the engine. Move code, regex, and other non-translatable content out of `CDATA` blocks first.
* `translate="no"` on any XML element excludes its content from translation.
* Files using ITS 2.0 external rules (`its:rules/@xlink:href`) currently return HTTP 500 — inline the rules or remove the reference.
* Malformed XML currently returns HTTP 500 instead of a 4xx. Validate with a standard XML parser before uploading.

**XLIFF**

* Only `<source>` content is translated; results are written to the corresponding `<target>`. **Existing `<target>` values are overwritten** — remove or split out already-translated units if you need to preserve them.
* The per-`<file>` `source-language` / `target-language` attributes are ignored — DeepL uses the API's `source_lang` and `target_lang` for the entire upload.
* `translate="no"` on `<trans-unit>` (1.2) or `<unit>` (2.0) is fully honored.
* The `state` attribute is preserved as-is; if you use `state="needs-translation"`, update it yourself after translation.
* An unsupported `trgLang` value on the root `<xliff>` element (e.g. `arb-MOD`) is rejected as "Invalid target language" even if the API `target_lang` is valid — remove or fix the attribute.

**DITA**

* Only DITA topic files (`.dita`) are supported. `.ditamap` uploads are rejected.
* `translate="no"` is fully honored on inline and block-level elements.
* Content references (`conref`, `conkeyref`) are not resolved — translate each referenced source topic independently.
* Newlines inside `<codeblock>`, `<pre>`, `<msgblock>`, and `<screen>` may be collapsed to single spaces. Move code samples out of the file before translation if line breaks matter.
* Topics with dense inline-element markup (combinations of `<filepath>`, `<cmdname>`, `<option>`, nested `<indexterm>`) may fail with an internal error — simplify or split the topic.

**JSON**

* Only string values are translated; keys, numbers, booleans, and `null` are not touched. Nested objects and arrays are traversed at every depth.
* Files must be strict, parseable JSON — no trailing commas, no comments. JSONC-style extensions are not supported.
* **Upload limit is 1 MB** regardless of plan. Large metadata payloads (e.g., DataCite, Zenodo, Backstage catalog dumps) may need to be split, or translated string-by-string via the text-translation API.
* Embedded HTML or Markdown inside string values (common in Contentful Rich Text and similar CMS payloads) is handled — DeepL translates the natural-language text and attempts to preserve the embedded markup. Review the output for complex rich-text content.
* Brace-delimited placeholders such as `{stars}` or `{{userName}}` are kept verbatim by default, so template variables survive translation. Multi-word groups such as `{see note}` are treated as translatable text. To translate placeholders along with the text, set `input_conversion_options=version:1,json-placeholders:translate` when uploading.
* ICU MessageFormat skeletons such as `{count, plural, one {# item} other {# items}}` are always protected: the variable name, keywords, and categories stay intact while the branch text is translated. Branch text is translated in isolation, so review plural forms in the output. Languages whose plural categories are absent from the source (for example Polish `few`/`many` from an English message) fall back to `other`. Expand categories in your i18n tooling if exact pluralization matters.
* To protect specific values from translation, encode them as non-strings (numbers/booleans/null) or pre-process the file to strip them.

**IDML**

* InDesign embeds font references, not the fonts themselves. If the target language uses characters not in the original font (e.g., Japanese in a Latin-only font), the output may show boxes or substituted glyphs — open the translated file in InDesign and swap fonts before distributing.
* Translated text is often longer than the source. Expect overset text (indicated by a red "+" in InDesign) in fixed-size frames; review and resize after translation.
* IDML does not use `translate="no"`. Protect content via InDesign character styles or by removing the affected text frames before exporting.

**MIF**

* The file must be genuine Adobe FrameMaker MIF. `.mif` files from other tools (e.g. Quartus memory-init files, MathML wrapped as MIF) currently return HTTP 500 rather than being rejected cleanly. Rename or convert them before uploading.
* MIF 8.00 and later are supported. Older MIF variants are best-effort — open and re-save from a recent FrameMaker version if the upload fails.
* Save as UTF-8 from FrameMaker before uploading; the file should begin with a `<MIFFile ...>` header.
* Some valid FrameMaker 10 MIF files may fail with HTTP 500 — try re-saving from a newer FrameMaker version.
* MIF does not use `translate="no"`. Protect content via FrameMaker conditional text or character formatting.

**XLSM** (currently in beta)

* Cell text is translated across all sheets; rich text formatting, merged cells, and multi-sheet layouts are preserved. Numbers and dates are left unchanged.
* Macros are preserved byte-for-byte and never translated. The VBA project is carried through untouched, so user-facing strings inside macro code remain in the source language.
* Formulas are preserved verbatim and cached values are kept as-is.
* Lookup formulas (`VLOOKUP`, `MATCH`, `INDEX`) whose lookup key is a text literal typed into the formula keep that literal in the source language while the table they search is translated, so the lookup can stop matching and return `#N/A` after recalculation. Key lookups off a cell reference (e.g. `=VLOOKUP(D1,...)`) instead.
* Files with no translatable text are rejected with `No translatable text can be extracted from the document.` This does not mean the file is malformed.

**SCORM (`.zip`)** (currently in beta)

* The `.zip` must be a valid SCORM package (SCORM 1.2 or SCORM 2004) with `imsmanifest.xml` at the root of the archive. AICC, xAPI (Tin Can), and cmi5 packages are not supported and are rejected.
* Course titles in `imsmanifest.xml` and lesson content in the package's HTML files are translated. Manifest identifiers, file paths, and HTML markup are preserved exactly.
* Audio and video files (MP3, MP4, WAV, images) are preserved byte-for-byte. DeepL does not transcribe or translate media content.
* Zip the contents, not the folder. `imsmanifest.xml` must sit at the root of the archive, exactly one. An archive that starts with a folder (e.g. `course/imsmanifest.xml`) is rejected.
* The manifest must be under 4 MB. A larger `imsmanifest.xml` is rejected.
* Non-SCORM `.zip` uploads are rejected with `400 Invalid or missing file extension`.

**VTT (WebVTT)** (currently in beta)

* Cue text is translated; cue timings, identifiers, settings lines, and `WEBVTT` headers are preserved so subtitles stay in sync with the original media.
* Inline styling tags (e.g. `<c>`, `<v Speaker>`, karaoke timestamps) are preserved. Review their placement, since translated text length differs from the source.
* Files with no translatable text are rejected.

**YAML / YML** (currently in beta)

* String values are translated at every level of nesting; keys, numbers, booleans, `null` values, comments, and indentation structure are preserved.
* Placeholders and escape sequences (`\n`, `\t`, etc.) are preserved.
* Files with no translatable text are rejected.
* Malformed YAML (inconsistent indentation, unquoted special characters) returns an error. Validate before uploading.

**Java `.properties`** (currently in beta)

* Property values are translated; keys and separators are preserved. Comment lines (`#` or `!`) are not translated.
* Placeholders (`{0}`, `%s`, `%d`) are normally preserved. Verify them after translation before shipping.
* Escaped characters (`\n`, `\t`, `\:`) are preserved.
* Files with no translatable text are returned unchanged.

**iOS/macOS `.strings`** (currently in beta)

* String values are translated; keys and the `"key" = "value";` structure are preserved.
* Format specifiers (`%@`, `%d`, positional specifiers like `%1$@`) are normally preserved. Verify them after translation before shipping.
* Escaped characters (`\n`, `\"`, `\\`) are preserved.
* Files with no translatable text are returned unchanged.

**Markdown (`.md` / `.markdown`)** (currently in beta)

* Paragraphs, headings, list items, blockquotes, table cell content, and image alt text are translated. URLs and link targets are not, only the link label text is.
* YAML front matter is not translated. **Known issue:** the `---` delimiters that open and close the front matter block are currently dropped from the translated file, which can fuse the metadata into the first paragraph. Re-add the `---` lines after download, or move the front matter out of the file before uploading.
* HTML blocks embedded in Markdown are processed via an HTML sub-filter. Results may vary for complex inline HTML.
* Markdown formatting (bold, italic, headings, lists) is preserved.
* Malformed Markdown is accepted and translated as-is (not validated for well-formedness).

**RESX** (currently in beta)

* String values in `<data>` elements are translated; element names, IDs, and XML structure are preserved. Comments in `<comment>` elements are not translated.
* Placeholders (`{0}`, `%s`) are normally preserved. Verify them after translation before shipping.
* Files with no translatable text are returned unchanged.

**ODT** (currently in beta)

* Body text, headings, table content, footnotes, endnotes, annotations, and document metadata are translated.
* Accept or reject all tracked changes before uploading. Deleted text that has not been formally removed may still be extracted and translated.
* Consecutive tabs may be dropped during translation. Review content that relies on tab-based alignment.
* If the target language requires characters outside the document's fonts, they may not render correctly. Check fonts after translation.

**RTF** (currently in beta)

* Body text in paragraphs, headings, list items, table cells, footnotes, and endnotes is translated. RTF control words, groups, and formatting tokens (`\b`, `\i`, `\par`, `\fonttbl`, etc.) are preserved untouched.
* Non-ASCII characters are written as `\uXXXX?` escape sequences. Old RTF readers that ignore `\u` escapes will show only the ASCII fallback character. Open the result in a modern reader (Word 2007+, LibreOffice).
* Embedded objects (images, OLE objects, embedded fonts) are preserved as binary blocks and not modified.
* Fields (`\field`) are preserved, but field instruction text is not translated. Only the displayed text result is.
* Hyperlink targets are not translated; only the link's display text is.

### Polling and translation time

Translation time depends on document size and server load: small documents typically finish in seconds, larger ones in 1-2 minutes once translation has started. Poll the [status endpoint](/api-reference/document/check-document-status) at regular intervals or with exponential backoff. Treat the `seconds_remaining` field as a rough estimate only; it can be unreliable and occasionally returns implausible values (e.g. 2^27).

### Using glossaries with documents

You can apply a glossary to a document translation with the `glossary_id` parameter (or up to 5 glossaries with `glossary_ids`). This requires the `source_lang` parameter to be set, and the glossary's language pair has to match the language pair of the request.

### Requesting a quality evaluation

A quality evaluation is a report on the translation DeepL just produced: for each segment of the document it lists the issues it detected, such as mistranslations, omissions, and fluency or style problems, with a severity and the character range each issue applies to. Use it to target human review at the segments that need it instead of reviewing the whole document. For a product overview, see [About quality evaluation for file translations](https://support.deepl.com/hc/en-us/articles/26360433777436-About-quality-evaluation-for-file-translations).

> [!WARNING]
>
> Quality evaluation is in [beta](/docs/resources/alpha-and-beta-features) and available to select customers only. To have it enabled for your account, contact your customer success manager; until then, opting in returns HTTP 403.

To request a quality evaluation, set [`enable_quality_evaluation`](/api-reference/document/upload-and-translate-a-document) to `true` when uploading a document.

When `enable_quality_evaluation=true`, three additional checks run before the translation request is accepted:

* The language pair must be in the [supported language pairs](/api-reference/quality-evaluations/poll#supported-language-pairs). Quality evaluation supports fewer language pairs than document translation.
* The file must be `docx`, `pptx`, `pdf`, `idml`, `xml`, `dita`, `mif`, or XLIFF 1.2/2.0/2.1. Quality evaluation supports fewer file types than document translation.
* Your account must have enough quality evaluation characters. Quality evaluation characters are metered separately from translation characters.

If any check fails, the request is rejected before translation starts, so nothing is translated or billed. Opting in never puts the translation itself at risk.

```bash theme={null}
curl -X POST https://api.deepl.com/v2/document \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --form 'source_lang=EN' \
  --form 'target_lang=DE' \
  --form 'file=@quarterly-report.docx' \
  --form 'enable_quality_evaluation=true'
```

The upload response carries a `quality_evaluation_job_id` alongside the usual document fields. It is the unique ID of the evaluation, and the value you poll with to retrieve the report:

```json theme={null}
{
  "document_id": "04DE5AD98A02647D83285A36021911C6",
  "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A",
  "quality_evaluation_job_id": "04DE5AD98A02647D83285A36021911C6"
}
```

Keep polling the [status endpoint](/api-reference/document/check-document-status) and downloading the translated document as you normally would. The report is a separate job, so poll for it separately:

```bash theme={null}
curl https://api.deepl.com/v1/quality-evaluations/04DE5AD98A02647D83285A36021911C6 \
  --header "Authorization: DeepL-Auth-Key $API_KEY"
```

While the evaluation is running you get HTTP 202 and `"status": "processing"`; wait the number of seconds in the `Retry-After` header and poll again. Expect this for a while after the translated document is ready, because the evaluation only starts once there is a translation to evaluate.

A finished evaluation returns HTTP 200 whether it succeeded or failed, so branch on `status` rather than the status code: `done` carries the report, and `error` means the evaluation could not be produced, for example because the language pair isn't supported.

```json theme={null}
{
  "job_id": "04DE5AD98A02647D83285A36021911C6",
  "status": "done",
  "segments": [
    {
      "segment_index": 0,
      "segment_score": 38.5,
      "source": "Our Q3 revenue came in 5% above forecast.",
      "target": "Unser Q3-Umsatz lag 5 % unter der Prognose.",
      "applied_glossary_term_pairs": [
        {
          "source_term": "forecast",
          "target_term": "Prognose",
          "ranges": [{ "start": 34, "end": 42 }]
        }
      ],
      "errors": [
        {
          "type": "Accuracy",
          "sub_type": "Mistranslation",
          "severity": "Critical",
          "explanation": "The source says revenue was '5% above forecast' but the translation says '5 % unter der Prognose' (5% below forecast). This reverses the meaning.",
          "source_spans": [{ "start": 23, "end": 31 }],
          "target_spans": [{ "start": 20, "end": 29 }]
        }
      ]
    }
  ]
}
```

Store the report as soon as it's `done`: reports are kept for [24 hours](/api-reference/quality-evaluations/poll#report-retention) after the evaluation finishes, and polling after that returns HTTP 404. For the severity and issue-type vocabulary, how to resolve `source_spans` and `target_spans`, and the applied glossary term pairs a report returns per segment, see the [quality evaluation reference](/api-reference/quality-evaluations/poll).

### Document format conversions

By default, the translated document comes back in the same format as the input. Two conversions differ:

* Translating a `.doc` file returns a `.docx` file.
* With the `output_format` parameter on upload, you can translate a PDF and receive an editable Microsoft Word document (`output_format=docx`). No other input formats support alternative output formats.

### Error 429: Too Many Requests

This error may occur when:

* You send concurrent document translation requests that exceed your account quota.
* You have too many un-retrieved or non-downloaded translated documents.

Documents are stored for only a brief period and must be downloaded promptly after translation.

To avoid this error, we recommend implementing the following measures:

* Polling document translation status, taking into account its frequency in order to prevent excessive load
* Quicker time to document retrieval
* Retries with exponential backoff

### Error 456: Quota Exceeded

This error indicates that your latest document translation request has exceeded the included characters (API Free) or the character limit you have set (API Pro) for your account.
Further document translation requests will not be processed.

> [!TIP]
>
> Check out our [code example](https://github.com/DeepL/deepl-node/tree/main/examples/bulk-translation) on how to implement bulk document translations.


# Error handling
Source: https://developers.deepl.com/docs/best-practices/error-handling

Parse DeepL API error responses, decide which status codes to retry, and throttle your client so it stays inside the API's limits.

Errors are indicated by [standard HTTP status codes](https://developer.mozilla.org/docs/Web/HTTP/Status). Branch on the status code first, then read the JSON body for detail. The expected status codes for each endpoint are listed with that endpoint in the [API Reference](/api-reference/translate/request-translation).

## Error response body

Error responses carry a JSON body. Parse it rather than the status text. You should also log the `X-Trace-ID` response header, as it will help our team debug if you need to raise a support ticket.

```json Example error response theme={null}
{
  "message": "Value for 'target_lang' not supported."
}
```

| **Field** | **Description** |
| - | - |
| `message` | Human-readable description of the error. Present on error responses |
| `code` | Machine-readable identifier for the error, where available. Branch on this rather than on `message`, which can change wording |

> [!WARNING]
>
> Don't match on `message` strings. They are written for humans and are not part of the API contract. Use the status code, and `code` where it is present.

Failures that occur before a request reaches the API, in DeepL's edge infrastructure, use a nested shape instead, with the message under an `error` object:

```json Example infrastructure error response theme={null}
{
  "error": {
    "message": "Bad Gateway."
  }
}
```

Handle both shapes in your parser. Reading `body.message ?? body.error?.message` covers every error the API can return, and keeps your client from crashing on a gateway error during an incident.

## Which errors to retry

| **Status** | **Meaning** | **Retry?** |
| - | - | - |
| `400` | The request itself is invalid | No. Fix the request |
| `403` | Authorization failed, or the API key lacks the [permission scope](/docs/admin/permission-scopes) for this endpoint | No. Check the key and its scopes |
| `404` | The resource does not exist, or a document has already been downloaded | No |
| `413` | The request exceeds the [request size limit](/docs/resources/usage-limits) | No. Split the payload into smaller requests |
| `429`, `529` | Too many requests in a short period | Yes, with exponential backoff |
| `456` | A usage limit was reached: the character quota for the billing period, a [Cost Control](/docs/best-practices/cost-control) or [key-level](/docs/admin/managing-api-keys#set-a-key-level-usage-limit) limit, or the number of glossaries your plan allows | No. Retrying will not succeed until the limit is raised, the period resets, or (for glossaries) you delete one |
| `500`, `503`, `504` | Temporary error in DeepL services | Yes, with exponential backoff |

Details on the errors you are most likely to hit:

* **HTTP 429: too many requests.** You may receive this when sending many API requests in a short period of time. Resend the request after a delay, using retries with exponential backoff. This is implemented in all of the official, DeepL-supported [client libraries](/docs/getting-started/client-libraries).

* **HTTP 456: quota exceeded.** The request would take the account or API key past one of its usage limits. The status code is the same for every cause, so log the `message` and `X-Trace-ID` to see which limit you hit:

  | **Cause** | **Returned by** | **What to do** |
  | - | - | - |
  | Your plan's character allowance is used up | Translate, Write, and other character-billed requests | **Free API users**: [upgrade your subscription](https://www.deepl.com/pro-api) for more character volume. **Pro API users**: buy additional characters or move to a larger plan |
  | A [Cost Control](/docs/best-practices/cost-control) limit was reached | Character-billed requests | Increase or remove the Cost Control limit |
  | A [key-level usage limit](/docs/admin/managing-api-keys#set-a-key-level-usage-limit) was reached | Requests made with that key | Raise the key's limit, or wait for the next usage period |
  | The account already has the maximum number of glossaries its plan allows | [Create a glossary](/api-reference/multilingual-glossaries/create-a-glossary) | Delete glossaries you no longer need, or [upgrade your plan](https://www.deepl.com/pro-api). See [glossary limits](/docs/customize/managing-glossaries#limits-and-restrictions) |

  Use the [usage endpoint](/api-reference/usage-and-quota/check-usage-and-limits) to check your current character usage and remaining quota before you hit a character limit.

* **HTTP 500: internal server error.** You'll receive this if there are temporary errors in DeepL services. Resend the request after a delay, using retries with exponential backoff. Check the [API Status Page](https://status.deepl.com/?tab=api) for current service availability and incident information.

## Throttling your client

The service dynamically adjusts to the load on the system, so there is no fixed request-per-second figure to code against. Design your client to find the limit rather than to assume one:

* Retry `429` and 5xx responses with exponential backoff and jitter. Honor the `Retry-After` header when a response includes one, in preference to your own backoff interval
* Cap the number of requests you have in flight at once, and lower that cap while you are receiving `429` responses
* Batch multiple strings into a single [translate request](/api-reference/translate/request-translation) instead of sending one request per string, staying inside the [request size limit](/docs/resources/usage-limits)
* Treat `456` as a stop condition, not a retry condition, and poll the [usage endpoint](/api-reference/usage-and-quota/check-usage-and-limits) to see how close an account is to its quota before you get there

As the service adapts to your traffic, you will be able to send increasingly more requests within a given amount of time without encountering errors.


# Estimating Character Usage
Source: https://developers.deepl.com/docs/best-practices/estimating-character-usage

Learn how to estimate your DeepL API character usage to find the right plan.

DeepL bills by the number of characters in your **source text**, measured in [Unicode code points](/docs/resources/usage-limits#your-usage). "A", "Δ", "あ", and "深" each count as one character. This means you can estimate your usage entirely on your own, without calling the API. All you need is access to your content.

This guide walks through techniques for counting characters in different content types, projecting monthly usage, and validating your estimates.

## Before you start

DeepL bills by source-text length in Unicode code points. Characters in the [`context` parameter](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter) and HTML/XML tags (when [tag handling](/docs/translate/translating-xml) is enabled) do not count. For the full billing rules and per-document character minimums, see [Usage and limits](/docs/resources/usage-limits#your-usage).

## Estimate website content

You don't need to crawl your entire site. Pick 5-10 representative pages (a mix of short and long ones), count the characters on each, and use the average to extrapolate across your total page count.

The script below strips HTML from a page and returns the character count. Run it against a handful of URLs to get your average.

```python theme={null}
from html.parser import HTMLParser
from urllib.request import urlopen

class TextExtractor(HTMLParser):
    def __init__(self):
        super().__init__()
        self.parts = []
        self._skip = False

    def handle_starttag(self, tag, attrs):
        self._skip = tag in ("script", "style", "noscript")

    def handle_endtag(self, tag):
        self._skip = False

    def handle_data(self, data):
        if not self._skip:
            self.parts.append(data)

    def get_text(self):
        return " ".join(self.parts)

def count_characters(url):
    html = urlopen(url).read().decode("utf-8", errors="replace")
    extractor = TextExtractor()
    extractor.feed(html)
    return len(extractor.get_text())

sample_urls = [
    "https://example.com/about",
    "https://example.com/products",
    "https://example.com/faq",
    "https://example.com/blog/recent-post",
    "https://example.com/contact",
]

total = 0
for url in sample_urls:
    chars = count_characters(url)
    total += chars
    print(f"{chars:>10,}  {url}")

avg = total // len(sample_urls)
print(f"\n{'Average':>10}  {avg:,} characters per page")
```

Then multiply the average by your total number of pages:

```
Estimated total = average characters per page × total pages on site
```

> [!TIP]
>
> If you want an exact count instead of a sample-based estimate, you can extend the script to crawl your full sitemap or use a crawler like [Scrapy](https://scrapy.org/) to discover all pages automatically.

## Estimate from a CMS or database

If your content lives in a CMS or a database, query it directly. This is often the most accurate approach because it reflects exactly what you'll send to the API.

Most CMSes (Drupal, WordPress, Contentful, etc.) do not provide a built-in way to see total word or character counts across all published content. You'll typically need to query the underlying database or use the CMS export/API to pull content and count locally.

```sql theme={null}
-- Example: estimate total characters across a content table
SELECT
    SUM(CHAR_LENGTH(body)) AS total_characters,
    COUNT(*) AS total_entries
FROM content
WHERE status = 'published';
```

For a Drupal site specifically, the `node_field_data` and `node__body` tables contain page titles and body content. For WordPress, query the `wp_posts` table filtering on `post_status = 'publish'`.

## Estimate document content

For documents you plan to translate via the [Document Translation API](/api-reference/document/upload-and-translate-a-document), you can extract text locally to get a rough character count.

```python theme={null}
import zipfile
import xml.etree.ElementTree as ET
import os

def count_docx_characters(path):
    with zipfile.ZipFile(path) as z:
        xml_content = z.read("word/document.xml")
    root = ET.fromstring(xml_content)
    ns = {"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"}
    texts = root.findall(".//w:t", ns)
    return sum(len(t.text) for t in texts if t.text)

for path in ["report.docx", "presentation.pptx"]:
    if os.path.exists(path):
        chars = count_docx_characters(path)
        print(f"{path}: {chars:,} characters")
```

For PDFs, use a library like PyMuPDF or pdfplumber to extract text.

Keep in mind that your local count is an approximation. DeepL's document processing pipeline may extract text differently than a local script, for example, by reading text embedded in images or charts via OCR. Treat your local count as a lower bound.

[Per-document character minimums](/docs/resources/usage-limits#maximum-upload-limits-per-document-format) apply for certain file formats, so the billed count may be higher than the actual text content.

## Project monthly usage

Once you know your total source characters, multiply by the number of target languages and your expected update frequency.

```
Monthly usage = source characters × target languages × update factor
```

For example, a website with 500,000 source characters translated into 5 languages with \~10% of pages updated monthly:

```
Initial translation:  500,000 × 5 = 2,500,000 characters
Monthly updates:      50,000  × 5 =   250,000 characters/month
```

If you're translating the same content into multiple languages, each language counts separately toward your character usage.

## Validate your estimate

Once you've estimated your characters, you can [sign up for a DeepL API plan for free](https://www.deepl.com/en/pro#api) and test a small sample against the live API. Use the [`show_billed_characters`](/api-reference/translate/request-translation) parameter to compare actual billed characters against your local count. DeepL intends to include `billed_characters` in responses by default in the future, with advance notice to API users before the change.

```bash theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header 'Authorization: DeepL-Auth-Key YOUR_AUTH_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "text": ["Sample text from your website or document."],
    "target_lang": "DE",
    "show_billed_characters": true
  }'
```

```json theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Beispieltext von Ihrer Website oder Ihrem Dokument."
    }
  ],
  "billed_characters": 46
}
```

Run this on 5-10 representative pages or documents and compare the `billed_characters` value against your local character count. They should be very close. Differences typically come from HTML tags or whitespace that your local extraction handles differently than the API.

## Monitor actual usage

After you start translating, monitor actual usage against your estimates:

* **[`/v2/usage` endpoint](/api-reference/usage-and-quota/check-usage-and-limits)** - programmatic access to your current billing period consumption
* **[Usage Analytics Dashboard](/docs/learning-how-tos/cookbook/usage-analytics-dashboard)** - visualize usage across API keys with the open-source demo dashboard
* **[API Usage Logger](/docs/learning-how-tos/cookbook/api-usage-logger)** - per-request logging with billed characters, language pairs, and reporting tags
* **[Cost Control](/docs/best-practices/cost-control)** - set a monthly character limit on your Pro API subscription to cap spend


# Language detection
Source: https://developers.deepl.com/docs/best-practices/language-detection

How DeepL detects the source language automatically, and why setting it yourself improves translation quality.

Our translation and document translation endpoints allow you to automatically detect the source language or set it. It is recommended to set the source language whenever possible, as this has a positive effect on translation quality. If you cannot specify the source language, the more context you provide, the better your results will be. Single words can lead to incorrect language detection, so the longer your text, the more reliable it will be.

If you are translating single words or very short sentences, the results will generally be more reliable if the source language is specified. You can find all available [source languages here](/api-reference/languages/retrieve-supported-languages), and you can read more about translation context in the next chapter.


# Pre-production checklist
Source: https://developers.deepl.com/docs/best-practices/pre-production-checklist

Here's what we recommend reviewing to get your DeepL API application ready for production.

As you prepare to open your DeepL-powered application up to the world, these tips will help you get ready for production.

1. **Error handling:** If you receive 429 or 500 errors, use retries with exponential backoff. If you use one of [DeepL's official client libraries](/docs/getting-started/client-libraries), you get this functionality out-of-the-box.
2. **Persistent HTTP connection:** Especially for use cases with low latency requirements, we recommend using a persistent HTTP connection. [DeepL's official client libraries](/docs/getting-started/client-libraries) use [Keep-Alive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Keep-Alive) by default.
3. **Use the correct content type:** For text translation (the `/translate` endpoint), use form-encoded (`Content-Type: application/x-www-form-urlencoded`) or JSON-encoded (`Content-Type: application/json`) request bodies.
   * Uploading a file for document translation requires an HTTP POST request with `Content-Type: multipart/form-data`; this content type should not be used for text translation.
4. **No query parameters:** Please do not make API requests using query parameters. The examples throughout the API reference include properly formed HTTP POST requests. For security reasons, be especially sure not to send your authentication key via query parameters.
5. **CORS requests:** It's not possible to send requests to the DeepL API from the browser, as requests to third-party APIs from front-end applications would expose your credentials on the web. [You can learn more here](/docs/best-practices/cors-requests).
6. **Translation context:** DeepL considers the broader context of a source text or document when translating. In general, including more context in a source text or document can result in a higher-quality DeepL translation. For text translation, you can also try the [`context` parameter](/api-reference/translate/request-translation). [Learn more about working with context here](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter).
7. **Cache results from translation requests:** Storing API responses lets apps serve content faster and avoids extra costs from repeated requests for unchanged content.


# Custom instructions
Source: https://developers.deepl.com/docs/customize/custom-instructions

Learn how to create effective custom instructions to customize your translation behavior

The `custom_instructions` parameter allows you to provide natural language instructions that customize how the DeepL API translates text. This guide provides best practices for creating effective custom instructions that produce consistent, high-quality results.

## What are custom instructions?

Custom instructions enable you to guide the translation engine with specific requirements for your use case. You can use custom instructions to:

* Control tone and style (e.g., "Use a friendly, diplomatic tone")
* Specify domain-specific terminology preferences
* Define formatting conventions
* Adjust formality levels beyond the standard `formality` parameter
* Provide context-specific guidance for specialized content

Custom instructions can also be used in conjunction with other features, such as glossaries, style rules, and the `context` parameter.

## How instructions are applied

Custom instructions are applied while the text is translated, sentence by sentence and passage by passage. They are not applied as an editing pass over the finished document. This makes them effective for local changes, such as word choice, tone, and the structure of individual sentences, and unreliable for changes that depend on seeing the whole text at once.

An instruction that describes the shape of the entire text, such as reordering an argument, converting lists into running text, or adding a summary, is applied to each passage individually. Instead of restructuring the document once, it restructures every passage, which typically lowers translation quality.

> [!WARNING]
>
> Write instructions that apply to the structure of one or more sentences, not to the structure of the entire text.

❌ **INCORRECT: Whole-text restructuring** — "Structure the text as a continuous chain: observation, problem framing, definition, implications"

✅ **CORRECT: Sentence-level structure** — "Split sentences longer than 25 words into two shorter sentences"

If you need the translated document restructured, translate it with local instructions only, then restructure the result in a separate step.

## Best practices

### 1. Write rules in English or the target language

Custom instructions should be written in either English or the target language. This ensures the translation engine can properly interpret and apply your instructions.

**English instruction** (works for all target languages) — "Use informal language appropriate for a mobile app"

**Target language instruction** (French) — "Utiliser un langage informel adapté à une application mobile"

### 2. Formulate rules positively

State what the translation should do, rather than what it should not do. Positive formulations are clearer and more effective.

❌ **INCORRECT: Negative formulation** — "Don't use overly formal language or avoid casual expressions"

✅ **CORRECT: Positive formulation** — "Use a conversational, friendly tone"

### 3. One instruction per rule

Each custom instruction should contain a single, focused directive. This makes your instructions clearer and more predictable.

❌ **INCORRECT: Multiple instructions combined** — "Use technical terminology, maintain formal tone, and convert measurements to metric"

✅ **CORRECT: Separate instructions**

* "Use technical terminology appropriate for engineers"
* "Maintain a formal, professional tone"
* "Convert imperial measurements to metric units"

### 4. Provide details on when and how to apply the rule

Include context about when the rule should be applied and specific guidance on how to apply it.

❌ **INCORRECT: Vague instruction** — "Handle gender appropriately"

✅ **CORRECT: Specific instruction with context** — "When translating role titles, use gender-neutral forms where available in the target language"

**Elements of a detailed instruction:**

* **When**: Conditions that trigger the rule
* **What**: Specific elements to modify
* **How**: Desired behavior or format

### 5. Avoid too many conditions per rule

Keep conditions simple and focused. Complex conditional logic reduces effectiveness.

❌ **INCORRECT: Too many conditions** — "If the text contains product names or brand terms, unless they appear in headings or quotes, and the context is marketing material rather than technical documentation, then capitalize all words except articles"

✅ **CORRECT: Simplified conditions**

* "Capitalize product names and brand terms in marketing content"
* "Preserve original capitalization in technical documentation"

### 6. Write instructions as translation directives, not chatbot prompts

Custom instructions guide translation behavior. They should be concise directives, not conversational prompts.

❌ **INCORRECT: Chatbot-style prompt** — "Please translate this text in a way that would be appropriate for a luxury fashion brand. Make sure to sound elegant and sophisticated, like you're speaking to a high-end clientele."

✅ **CORRECT: Clear translation directive** — "Use elegant, sophisticated language appropriate for luxury fashion"

## Combining multiple instructions

All active instructions apply to every translation together; there is no priority order among them. However, the broader and more transformative an instruction is, the more strongly it shapes the output. A single instruction that rewrites heavily can drown out the effect of your more specific instructions.

To keep a set of instructions predictable:

* Add instructions one at a time, and test each against representative source texts before adding the next
* Keep each instruction local and specific, following the best practices above
* If translation quality drops after a change, remove the broadest instruction first and retest

## Technical constraints

When using custom instructions, keep these constraints in mind:

* **Maximum instructions**: Up to 10 custom instructions per request
* **Character limit**: Each instruction can contain a maximum of 300 characters
* **Supported target languages**: See [Languages supported](/docs/getting-started/supported-languages)
* **Model compatibility**: Custom instructions are compatible with all `model_type` values.

## Related documentation

* [Text translation API reference](/api-reference/translate/request-translation)
* [Working with context](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter)
* [Style rules API](/docs/customize/using-style-rules)
* [Multilingual glossaries](/docs/customize/managing-glossaries)


# How to Apply Glossaries to Language Variants
Source: https://developers.deepl.com/docs/customize/customizations-for-variants

Learn how to apply glossaries when translating into language variants like FR-CA or EN-GB.

DeepL supports regional language variants such as `PT-BR` vs `PT-PT`, or `FR-CA` vs `FR-FR`. When applying glossaries, customizations must be created using the root language code, but can be applied to any variant of that language.

**This guide shows you:**

* How to create glossaries using root language codes (e.g. `PT`, `FR`)
* How to pass a glossary when translating into a variant target (e.g. `pt-BR`, `fr-CA`)
* A practical example of using variant-specific glossaries to enforce locale-appropriate terminology

## Creating a glossary for a language

DeepL distinguishes between root language codes (e.g. `pt`) and language variant codes (e.g. `pt-BR`). Glossaries must be created with the root code. Attempting to create one with a variant code will fail.

| **Use this** | **Not this** |
| :- | :- |
| `zh` | `zh-Hant`, `zh-Hans` |
| `pt` | `pt-BR`, `pt-PT` |
| `fr` | `fr-CA`, `fr-CH` |
| `de` | `de-CH` |
| `it` | `it-CH` |
| `es` | `es-ES`, `es-419` |

See [supported languages](/docs/getting-started/supported-languages) for the full list.

> [!NOTE]
>
> This restriction only applies to glossaries. Other customizations like style rules support language variants.

The following example creates two glossaries to enforce different terms for "invoice" in Brazilian and European Portuguese. Both use the root language code `PT`:

```python Example: Create glossaries with root language codes theme={null}
import deepl

translator = deepl.Translator("YOUR_AUTH_KEY")

glossary_br = translator.create_glossary(
    "PT-BR Invoice Glossary",
    source_lang="EN",
    target_lang="PT",        # root code — not PT-BR
    entries={"invoice": "nota fiscal"}
)

glossary_pt = translator.create_glossary(
    "PT-PT Invoice Glossary",
    source_lang="EN",
    target_lang="PT",        # root code — not PT-PT
    entries={"invoice": "fatura"}
)
```

## Applying a glossary to a language variant

Once a glossary is created with a root language code, pass its ID in the `/translate` call with a variant `target_lang`:

```python Example: Apply glossaries to variant targets theme={null}
result_br = translator.translate_text(
    "Your invoice is ready to view.",
    source_lang="EN",
    target_lang="PT-BR",
    glossary=glossary_br.glossary_id
)

result_pt = translator.translate_text(
    "Your invoice is ready to view.",
    source_lang="EN",
    target_lang="PT-PT",
    glossary=glossary_pt.glossary_id
)

print(result_br.text)  # Sua nota fiscal está pronta para ser visualizada.
print(result_pt.text)  # A sua fatura está pronta a ser visualizada.
```

## CAT tools

Some CAT tools may prevent applying a glossary linked to a root code language when the target language is a variant. This is an incorrect limitation that does not reflect the DeepL API's behavior. You'll need to reach out to your CAT tool provider to request this restriction is removed.

***

## Next steps

* **Apply glossaries in practice:** See [Glossaries in the real world](/docs/customize/glossaries-in-the-real-world) for a full worked example
* **Translate between variants:** Learn about the Write API and style rules in [How to translate between language variants](/docs/learning-how-tos/examples-and-guides/translating-between-variants)
* **Improve translation quality:** See how [the context parameter](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter) can further refine your translations


# Glossaries in the Real World
Source: https://developers.deepl.com/docs/customize/glossaries-in-the-real-world

A quick guide to using DeepL glossaries in translations

### What are glossaries and why should you care?

A great feature of DeepL API is the ability to improve consistency when translating content across multiple languages. As an API user you can do this by including glossaries in your translations, which allow you to fine-tune how words and phrases should be translated from one language to another.

This is perfect for situations where technical terms or product information needs to be standardized - saving time and money by reducing the need for manual editing in a translation workflows.

### A simple example from The Acme Startup Company

The best way to show how something works is to use a real world use case, and for this we’re heading to the cool headquarters of (the completely fictional) Acme Startup Company.

Acme have customers from all over the world and offer support over email and their in-app chat system. Their support staff work around the globe in order to provide 24 hour support, but different time zones and language difference might mean customers get a different experience each time they speak to an agent. Saying “***Good morning***” to a customer when it’s 7pm for them doesn’t sound great.

Acme prides itself on the quality of its support and wants to standardize how support agents interact with customers without removing human interaction. Acme reviewed the chat and email transcripts of a cross section of customer service messages, and built an initial list of the words and phrases they wanted to standardize when a customer is greeted.

Let’s dive in and help Acme out!

### Getting started

First, we’re going to need a DeepL account in order to get hold of an API key so we can authenticate our API requests. For this demo, we’re going to use the DeepL Python client library in order to make the API requests, but all the glossaries functionality is available using cURL or any of our other client libraries. Check out the API docs and DeepL GitHub for more information.

First, we’ll install the DeepL Python library from the command line:

`pip install --upgrade deepl`

From here we can start putting together our Python code. In a file called **main.py**, We’ll begin by constructing a translator object, including your own auth key you can find in your account:

```python main.py theme={null}
import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)
```

And finally, we’ll send a simple translation request, with an example of what Acme are currently experiencing:

```python main.py theme={null}
import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)
result = translator.translate_text("Good evening, Gabrielle", target_lang="DE")
print(result.text) # "Guten Abend, Gabrielle"
```

As you can see, if Gabrielle was receiving this in the morning of their time zone, it might not set the right tone Acme are looking for in their customer service quality. Let’s help Acme out by creating a simple solution using a Glossary.

### Creating a Glossary

To create our glossary, we’ll create a new file called **`glossary.py`** - this is because we only need to create the glossary once. Start with the same code to construct a translator object:

```python glossary.py theme={null}
import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)
```

Then, we can create a list of entries we want to recognize and change when translating from English to German:

```python glossary.py theme={null}
import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)

entries = {"Good morning": "Hallo",  # "Guten Morgen"
          "Good afternoon": "Hallo", # "Guten Tag"
          "Good evening" : "Hallo",  # "Guten Abend"
          "Greetings": "Hallo",      # "Grüße"
          "Dear": "Hallo"}           # "Liebe"
```

Lastly, we create the glossary by calling `translator.create_glossary`, giving it a name, setting the source and target languages, and assigning the entries we just created:

```python glossary.py theme={null}
import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)

entries = {"Good morning": "Hallo",  # "Guten Morgen"
          "Good afternoon": "Hallo", # "Guten Tag"
          "Good evening" : "Hallo",  # "Guten Abend"
          "Greetings": "Hallo",      # "Grüße"
          "Dear": "Hallo"}           # "Liebe"
          
acme_glossary = translator.create_glossary(
  "Greetings Glossary",
  source_lang="EN",
  target_lang="DE",
  entries=entries,
)

print(acme_glossary.glossary_id) # "def3a26b-3e84..."
```

Running `glossary.py` will give us a response containing `glossary_id`, which we can add to our initial translation in `main.py`. Also be aware that when using a glossary, you will also need to include `source_lang` as part of your request:

```python main.py theme={null}
import deepl
auth_key = "19f172ae-03a9-..."
translator = deepl.Translator(auth_key)

result = translator.translate_text("Good evening, Gabrielle", source_lang="EN", target_lang="DE", glossary="def3a26b-3e84...")

print(result.text) # "Hallo, Gabrielle"
```

You’ll now see that the greeting of “***Guten Abend, Gabrielle***” has now been replaced with the much more consistent “***Hallo, Gabrielle***”. Try changing “***Good evening***” to “***Good morning***”, and you’ll see the Glossary doing its job and keeping all customer service messaging in harmony.

### Wrapping up

This has been a really simple - but powerful - example to highlight how glossaries can help organizations maintain quality, accuracy and consistency in their messaging across multiple languages. Although this was a small snapshot into how glossaries could be used to make greetings consistent, it’s clear just how powerful glossaries can be when expanded into covering content such as product catalogs or technical documentation, where consistent naming is crucial.

Glossaries are incredibly flexible and give you the power to fine-tune your translations. Some more examples for you to try out could be:

* Always changing “***Vereinigtes Königreich***” to “***UK***” (rather than “United Kingdom”)
* Updating “***pharmacy***” in locales where it is more common to say “***chemist***” or “***drug store***”
* Ensuring “***Casques d'écoute***” always translates to “***headphones***” in a product catalog (instead of potentially “headset”)


# Glossary v2 vs v3 Endpoints
Source: https://developers.deepl.com/docs/customize/glossary-v2-vs-v3-endpoints

How the v3 glossary endpoints differ from the deprecated v2 endpoints, what to watch out for when mixing them, and how to work with v2's immutability.

DeepL's API has two generations of glossary endpoints. The [v2 endpoints](/api-reference/glossaries/create-a-glossary) create, delete, and retrieve **monolingual** glossaries: glossaries that map one language to another. The [v3 endpoints](/api-reference/multilingual-glossaries/create-a-glossary) include all v2 functionality, plus:

* v3 lets you **edit** glossaries
* v3 supports **multilingual** glossaries: a collection of dictionaries covering multiple language pairs

We recommend using v3 for all glossary work; v2 is kept for backward compatibility. There is no need to migrate your existing glossaries: you can use v3 endpoints with any glossary, whichever version created it. Glossaries from either version work in all translation endpoints, both [`/translate`](/api-reference/translate/request-translation) and [`/document`](/api-reference/document/upload-and-translate-a-document).

## Differences between v2 and v3

A v2 glossary is a single list of mappings with one source and one target language:

```json theme={null}
{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "My Glossary",
  "source_lang": "en",
  "target_lang": "de",
  "entries": {
    "Hello": "Hallo"
  },
  "creation_time": "2025-08-03T14:16:18.329Z"
}
```

A v3 glossary holds a collection of **dictionaries**, each with its own language pair. The same glossary can carry the reverse mapping too:

```json theme={null}
{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "My Glossary",
  "dictionaries": [
    {
      "source_lang": "en",
      "target_lang": "de",
      "entries": {
        "Hello": "Hallo"
      }
    },
    {
      "source_lang": "de",
      "target_lang": "en",
      "entries": {
        "Hallo": "Hello"
      }
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}
```

The v3 endpoints handle glossary management only; use v2 for everything else, including translation itself. The deprecated `/v2/glossary-language-pairs` endpoint is also superseded: use [`GET /v3/languages?resource=glossary`](/docs/languages/using-the-languages-api) instead.

## Can I keep using v2?

You can, but we recommend switching: new features land on v3, and the v2 glossary endpoints may be deprecated or removed at some point. If an immediate switch isn't possible, keep these implications in mind:

* Once a glossary has been edited via v3, v2 endpoints can no longer query it correctly (for example, the "get entries" call). To avoid data loss, deleting such a glossary through v2 is disabled; use the v3 deletion endpoint.
* Avoid mixing versions across a team or codebase. Glossaries created via v3 are still queryable via v2, where they can't be displayed correctly, which causes confusion.

> [!WARNING]
>
> Don't use both v2 and v3 glossary endpoints in the same integration. Editing a glossary via v3 changes how it behaves on v2 endpoints.

## Editing under v2: the workaround

v2 glossaries are immutable: once created, the entries for a given glossary ID cannot be modified. If you stay on v2, identify glossaries by **name** instead of ID in your application, and modify them with this procedure:

1. [Retrieve](/api-reference/glossaries/retrieve-glossary-entries) and store the current glossary's entries
2. Modify the entries locally
3. [Delete](/api-reference/glossaries/delete-a-glossary) the existing glossary
4. [Create a new glossary](/api-reference/glossaries/create-a-glossary) with the same name

On v3, none of this is necessary; edit dictionaries directly as shown in [Managing Glossaries](/docs/customize/managing-glossaries).

## Client libraries

Each of our [client libraries](/docs/getting-started/client-libraries) provides a guide explaining how to migrate its glossary support to v3.


# Improving Transcription with Spoken Terms
Source: https://developers.deepl.com/docs/customize/improving-transcription-with-spoken-terms

Keep company names, acronyms, and product terminology transcribed correctly in Voice API sessions by creating and maintaining a Spoken Terms collection.

In Voice API sessions, Spoken Terms ensure that the vocabulary that matters to you, such as company names, acronyms, product names, and people's names, is transcribed with the exact spelling you choose. You provide the words, and speech recognition uses your spelling whenever they're spoken. Unlike [glossaries](/docs/customize/managing-glossaries), Spoken Terms are monolingual. They affect how speech is recognized, not how the recognized text is translated.

This guide shows you how to set up Spoken Terms via the API and keep them current as your vocabulary grows. You can also manage them in [DeepL Home](https://www.deepl.com/en/voice/spoken-terms).

> [!NOTE]
>
> Spoken Terms are available on all plans that include the DeepL Voice API. The number of collections you can create depends on your [plan](https://www.deepl.com/en/pro#api).

## Collect domain-specific terms

Review your calls for domain- and company-specific words you want transcribed with complete accuracy. Collect them in a **term list**: the terms, written exactly as you want them to appear in your transcripts (terms are case-sensitive). In the next step, you'll send this list to the DeepL API.

```text theme={null}
DeepL
API
webhook
```

Each term list holds at most 300 characters in total (see [Spoken Terms Requirements](/docs/customize/spoken-terms-requirements) for all size and content rules), so spend the budget on the terms that matter most rather than your full vocabulary.

## Create a collection

Term lists are stored in a **Spoken Terms collection**, which can hold one term list for each language. Create a collection with [`POST /v3/spoken-terms`](/api-reference/spoken-terms/create-spoken-terms-collection):

```sh Example request theme={null}
curl -X POST https://api.deepl.com/v3/spoken-terms \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Technical Terms",
    "term_lists": [
      {
        "lang": "en",
        "entries": "DeepL\nAPI\nwebhook"
      }
    ]
}'
```

```json Example response theme={null}
{
  "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "Technical Terms",
  "term_lists": [
    {
      "lang": "en",
      "entry_count": 3
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}
```

Store the `spoken_terms_id`; every voice session that should use these terms passes it.

## Start a voice session with your terms

Include the `spoken_terms_id` when you [create a voice session](/api-reference/voice/request-session). The terms for the session's source language are then recognized correctly in the transcription:

```sh Example request theme={null}
curl -X POST https://api.deepl.com/v3/voice/realtime \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "source_media_content_type": "audio/pcm; encoding=s16le; rate=16000",
    "source_language": "en",
    "target_languages": ["de"],
    "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
}'
```

See the [Real-Time Voice Quickstart](/docs/voice/real-time-voice-quickstart) for an example of the full Voice API session flow.

To also control how your terms are **translated**, pass a `glossary_id` in the same session. Spoken Terms control how speech is recognized, and glossaries control how it's translated.

Spoken Terms are available for all [DeepL Voice languages](https://support.deepl.com/hc/en-us/articles/26625846174364-DeepL-Voice-languages). To check a language programmatically, call [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) and look for the `spoken_terms` feature key on the source language.

## Add terms as your vocabulary grows

To add terms without resending the existing ones, [`PATCH` the collection](/api-reference/spoken-terms/edit-spoken-terms-details); entries you pass for a language are merged into its existing term list:

```sh Example request theme={null}
curl -X PATCH https://api.deepl.com/v3/spoken-terms/def3a26b-3e84-45b3-84ae-0c0aaf3525f7 \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "term_lists": [
      {
        "lang": "en",
        "entries": "authentication\nendpoint"
      }
    ]
}'
```

```json Example response theme={null}
{
  "spoken_terms_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "name": "Technical Terms",
  "term_lists": [
    {
      "lang": "en",
      "entry_count": 5
    }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}
```

Running sessions aren't affected; the updated terms apply to sessions started after the change.

## Replace a language's terms

To rebuild a language's term list from scratch, for example from an updated product catalog, [`PUT` the term list](/api-reference/spoken-terms/replace-or-create-term-list) with the new entries. Unlike `PATCH`, which adds to the existing list, `PUT` replaces the list entirely (or creates it, if the language is new to the collection):

```sh Example request theme={null}
curl -X PUT https://api.deepl.com/v3/spoken-terms/def3a26b-3e84-45b3-84ae-0c0aaf3525f7/term-lists \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "lang": "en",
    "entries": "DeepL\nAPI\nwebhook\nintegration"
}'
```

```json Example response theme={null}
{
  "lang": "en",
  "entry_count": 4
}
```

See the [Spoken Terms reference](/api-reference/spoken-terms/create-spoken-terms-collection) for full details on managing collections. Size and content rules are collected in [Spoken Terms Requirements](/docs/customize/spoken-terms-requirements).


# Managing Glossaries
Source: https://developers.deepl.com/docs/customize/managing-glossaries

Create, edit, retrieve, and delete DeepL glossaries with the v3 endpoints, and apply them in translation requests.

Glossaries let you specify exact translations for words and short phrases. During translation, DeepL intelligently flexes entries to account for case, gender, tense, and other grammar features when the target language has flexion. This guide shows how to manage glossaries programmatically with the [v3 glossary endpoints](/api-reference/multilingual-glossaries/create-a-glossary) and apply them in translations.

A **glossary** contains one or more **dictionaries**. A dictionary maps source phrases to target phrases for a single language pair, in one direction:

| **French →** | **Spanish** |
| :- | :- |
| belle | hermosa |
| delicieux | exquisito |

To apply the same terminology in both directions, add a second dictionary with the reverse mapping (Spanish → French). You can create dictionaries for [any language that supports glossaries](/docs/getting-started/supported-languages); to check programmatically, call [`GET /v3/languages?resource=glossary`](/docs/languages/using-the-languages-api).

> [!TIP]
>
> If you're new to glossaries, start with [Glossaries in the Real World](/docs/customize/glossaries-in-the-real-world), a hands-on tutorial that builds one from scratch.

## Entry formats

Glossary entries are formatted as CSV (comma-separated values) or TSV (tab-separated values), one entry per line, source phrase first:

```csv CSV entries theme={null}
hermosa,belle
exquisito,delicieux
```

You can also enclose each phrase in quotation marks. CSV entries follow standard CSV conventions:

* Fields containing double quotes or commas must be enclosed in double quotes
* A double quote inside a quoted field is escaped by doubling it (`""`)

TSV is identical except that a tab separates the source and target phrases. In CSV, you can optionally append the source and target language after the phrases; entries whose languages don't match the dictionary's language pair are ignored.

## Create a glossary

Send `POST /v3/glossaries` an array of one or more dictionaries. This example creates a glossary with an English → German dictionary and its reverse:

```sh Example request theme={null}
curl -X POST https://api.deepl.com/v3/glossaries \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "My Glossary",
    "dictionaries": [
      {
        "source_lang": "en",
        "target_lang": "de",
        "entries": "Hello\tGuten Tag",
        "entries_format": "tsv"
      },
      {
        "source_lang": "de",
        "target_lang": "en",
        "entries": "Guten Tag\tHello",
        "entries_format": "tsv"
      }
    ]
}'
```

```json Example response theme={null}
{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "ready": true,
  "name": "My Glossary",
  "dictionaries": [
    { "source_lang": "en", "target_lang": "de", "entry_count": 1 },
    { "source_lang": "de", "target_lang": "en", "entry_count": 1 }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}
```

To create a glossary from an existing CSV file on the command line, use [`jq`](https://jqlang.github.io/jq/) to embed the file contents in the request body:

```sh Create a glossary from a CSV file theme={null}
curl -X POST https://api.deepl.com/v3/glossaries \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data "$(jq -Rs '{
    "name": "My Glossary",
    "dictionaries": [
      {
        "source_lang": "en",
        "target_lang": "de",
        "entries": .,
        "entries_format": "csv"
      }
    ]
  }' glossary.csv)"
```

## Use a glossary in a translation

Include the `glossary_id` in a [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) request. You must also set `source_lang`: glossaries can't yet be used with automatic source language detection.

```sh Example request theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": ["Hello"],
    "source_lang": "EN",
    "target_lang": "DE",
    "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
}'
```

```json Example response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Guten Tag"
    }
  ]
}
```

Glossaries apply to root languages, not specific variants: a glossary with target language `EN` applies when translating into `EN-US` and `EN-GB` alike, and must be created with the root code. See [How to Apply Customizations to Language Variants](/docs/customize/customizations-for-variants).

The `v3` endpoints handle glossary management only; translation itself stays on the `v2` endpoints.

## Edit a glossary

Two methods change an existing glossary, with different semantics:

| Method | Scope | Behavior |
| :- | :- | :- |
| [`PUT /v3/glossaries/{id}/dictionaries`](/api-reference/multilingual-glossaries/replaces-or-creates-a-dictionary-in-the-glossary-with-the-specified-entries) | One dictionary | Creates the dictionary for the given language pair, or **replaces** it entirely if it exists |
| [`PATCH /v3/glossaries/{id}`](/api-reference/multilingual-glossaries/edit-glossary-details) | Whole glossary | Updates metadata like the name; entries passed for a language pair are **merged** into the existing dictionary |

For example, this `PATCH` renames a glossary and adds one entry to its English → German dictionary, keeping existing entries:

```sh Example request theme={null}
curl -X PATCH https://api.deepl.com/v3/glossaries/def3a26b-3e84-45b3-84ae-0c0aaf3525f7 \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Gertrude the glossary",
    "dictionaries": [{
      "source_lang": "en",
      "target_lang": "de",
      "entries": "Goodbye\tTschüß",
      "entries_format": "tsv"
    }]
}'
```

A single `PUT` or `PATCH` can change one dictionary. To change the same source phrase across multiple language pairs, make one call per dictionary.

## Retrieve glossaries

* [`GET /v3/glossaries`](/api-reference/multilingual-glossaries/list-all-glossaries) lists all your glossaries with per-dictionary metadata (no entries)
* [`GET /v3/glossaries/{id}`](/api-reference/multilingual-glossaries/retrieve-glossary-details) returns one glossary's metadata
* [`GET /v3/glossaries/{id}/entries`](/api-reference/multilingual-glossaries/retrieve-glossary-entries) returns the entries of a single dictionary, selected via `source_lang` and `target_lang` query parameters. Entries are currently returned in TSV format only.

To retrieve the contents of an entire glossary, iterate over its dictionaries and fetch each one's entries.

## Delete glossaries

* [`DELETE /v3/glossaries/{id}`](/api-reference/multilingual-glossaries/delete-a-glossary) deletes the whole glossary
* [`DELETE /v3/glossaries/{id}/dictionaries?source_lang=...&target_lang=...`](/api-reference/multilingual-glossaries/deletes-the-dictionary-associated-with-the-given-language-pair-with-the-given-glossary-id) deletes a single dictionary

## Limits and restrictions

* Each dictionary can contain up to 10 MB of entries; a glossary with five dictionaries can hold up to 50 MB in total
* The glossary name, each source phrase, and each target phrase can contain up to 1024 UTF-8 bytes
* Duplicate source entries are not allowed, and neither source nor target may be empty
* Entries must not contain control characters (such as `\t` or `\n` inside a phrase), Unicode newlines, or leading/trailing whitespace
* The number of glossaries per account is [limited by your plan](https://www.deepl.com/en/pro-api)


# Customize
Source: https://developers.deepl.com/docs/customize/overview

Tailor DeepL translations to your domain with glossaries, style rules, custom instructions, and translation memories.

DeepL's customization features let you control terminology, style, and consistency across your translations.

## What each feature does

| Feature | What it controls | How it's applied |
| :- | :- | :- |
| [Glossaries](/docs/customize/managing-glossaries) | Exact translations for specific terms, like product names or industry vocabulary | Stored on your account; passed per request via `glossary_id` |
| [Style rules](/docs/customize/using-style-rules) | Formatting conventions (dates, numbers, punctuation) plus stored custom instructions | Stored on your account; passed per request via `style_id` |
| [Custom instructions](/docs/customize/custom-instructions) | Tone, phrasing, and domain-specific behavior via natural-language directives | Inline per request via `custom_instructions`, or stored in a style rule list |
| [Translation memories](/docs/customize/using-translation-memories) | Reuse of your previously approved translations for matching segments | Stored on your account; passed per request via `translation_memory_id` |
| [Spoken terms](/docs/customize/improving-transcription-with-spoken-terms) | Recognition of specific terms during Voice API speech transcription | Stored on your account; passed per voice session via `spoken_terms_id` |
| [Style profiles](/docs/customize/using-style-profiles) | A named bundle of glossaries, style rules, and translation memories | Stored on your account; passed per request via `style_profile_id` instead of the individual parameters |

Glossaries, style rules, custom instructions, and translation memories work with both [text translation](/docs/translate/translate-text-quickstart) and [document translation](/docs/translate/translate-documents-quickstart), support all `model_type` values, and can be combined in a single request. A style profile bundles glossaries, style rules, and translation memories under one ID for both text and document translation, and is used in place of the individual parameters. Spoken terms apply to [Voice API](/docs/voice/overview) sessions, where they can be combined with glossaries.

> [!WARNING]
>
> Glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using [regional endpoints](/docs/getting-started/regional-endpoints) can't access glossaries or style rules created in the UI at this time.

## Choosing the right feature

Here's when to use each customization feature for the best results. The [`context` parameter](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter) can also be used to improve translations of ambiguous or short text.

| Use case | Glossaries | Style rules | Custom instructions | Translation memories | Context parameter |
| :- | :-: | :-: | :-: | :-: | :-: |
| **Consistent domain-specific terminology** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Brand and product names** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Formatting conventions (dates, numbers, punctuation)** | ❌ | ✅ | ❌ | ❌ | ❌ |
| **Tone and phrasing** | ❌ | ❌ | ✅ | ❌ | ❌ |
| **Reusing previously approved translations** | ❌ | ❌ | ❌ | ✅ | ❌ |
| **Ambiguous words or short snippets** | ❌ | ❌ | ❌ | ❌ | ✅ |
| **Consistent gender or name spelling** | ❌ | ❌ | ❌ | ❌ | ✅ |

## Feature guides

> **[Managing Glossaries](/docs/customize/managing-glossaries)**
>
> Create, edit, retrieve, and delete glossaries with the v3 endpoints, and use them in translations.

> **[Using Style Rules](/docs/customize/using-style-rules)**
>
> Build style rule lists with configured rules and custom instructions, and apply them via style\_id.

> **[Custom Instructions](/docs/customize/custom-instructions)**
>
> Best practices for writing natural-language instructions that produce consistent results.

> **[Using Translation Memories](/docs/customize/using-translation-memories)**
>
> Retrieve your translation memories and control the matching threshold in translation requests.

> **[Improving Transcription with Spoken Terms](/docs/customize/improving-transcription-with-spoken-terms)**
>
> Keep company terms, acronyms, and names transcribed correctly in Voice API sessions.

> **[Using Style Profiles](/docs/customize/using-style-profiles)**
>
> Bundle glossaries, style rules, and translation memories under one ID and apply them in a single parameter.

## API reference

Glossaries, style rules, translation memories, and style profiles each have management endpoints under the [API Reference](/api-reference/multilingual-glossaries/create-a-glossary). If you're still on the deprecated v2 glossary endpoints, see [Glossary v2 vs v3 Endpoints](/docs/customize/glossary-v2-vs-v3-endpoints) for the differences and migration considerations.


# Spoken Terms Requirements
Source: https://developers.deepl.com/docs/customize/spoken-terms-requirements

Size limits and content rules for Spoken Terms collections and term lists.

## Size limits

| Item | Limit |
| :- | :- |
| Characters per term list | 300 total |
| Collection name | 1024 UTF-8 bytes |
| Collections per account | Limited by your [plan](https://www.deepl.com/en/pro#api) |

Names using only ASCII characters can be up to 1024 characters long; names with multi-byte characters hold fewer.

## Content rules

* Terms are case-sensitive
* Duplicate terms within a list are not allowed (comparison is case-sensitive)
* Terms must not be empty
* Terms must not contain C0 or C1 control characters (including tabs `\t` or newlines `\n` within a term)
* Terms must not contain leading or trailing whitespace

## Availability

Spoken Terms are available on all plans that include the DeepL Voice API, for all [DeepL Voice languages](https://support.deepl.com/hc/en-us/articles/26625846174364-DeepL-Voice-languages). To check a language programmatically, call [`GET /v3/languages?resource=voice`](/api-reference/languages/retrieve-languages-by-resource) and look for the `spoken_terms` feature key on the source language.


# Using Style Profiles
Source: https://developers.deepl.com/docs/customize/using-style-profiles

Bundle glossaries, style rule lists, and translation memories into a style profile and apply them to translations with the style_profile_id parameter.

A style profile bundles the customizations you use together, such as the glossary, style rule list, and translation memory for one product or client, under a single ID. Instead of passing `glossary_ids`, `style_id`, and `translation_memory_id` with every request, you pass one `style_profile_id`. When the bundle changes, you update the profile, not your integration.

A style profile can link:

* **Glossaries**: any number, optionally with a priority order
* **Style rule lists**: at most one per target language
* **Translation memories**: at most one per source language

Manage style profiles with the [style profiles endpoints](/api-reference/style-profiles/list-all-style-profiles), as shown below.

## Create a style profile

Send `POST /v3/style_profiles` a name and the IDs of the components to link. Only `name` is required, so you can also create an empty profile and link components later.

```sh Example request theme={null}
curl -X POST https://api.deepl.com/v3/style_profiles \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Legal, German",
    "description": "Contract wording for the German market.",
    "industry": "Legal",
    "glossary_ids": ["4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81"],
    "style_rule_ids": ["bd0a38f3-1831-440b-a8dd-2c702e2325ab"],
    "translation_memory_ids": ["a74d88fb-ed2a-4943-a664-a4512398b994"]
}'
```

```json Example response theme={null}
{
  "style_profile_id": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47",
  "name": "Legal, German",
  "description": "Contract wording for the German market.",
  "industry": "Legal",
  "glossary_ids": ["4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81"],
  "style_rule_ids": ["bd0a38f3-1831-440b-a8dd-2c702e2325ab"],
  "translation_memory_ids": ["a74d88fb-ed2a-4943-a664-a4512398b994"],
  "glossary_priority_order_enabled": false,
  "creation_time": "2026-04-01T16:34:25.223Z",
  "updated_time": "2026-04-01T16:34:25.223Z"
}
```

If one of the IDs doesn't exist or isn't accessible to your account, the request fails with `400 Bad Request` and no profile is created. The error message names the list that contains the bad ID, for example `Check 'glossary_ids'`.

The glossaries, style rule lists, and translation memories you link don't have to share a language pair. A profile can hold an English and a Japanese style rule list at the same time, and each one is used only for its own target language.

## Translate with a style profile

Pass the `style_profile_id` in a [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) request:

```sh Example request theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": ["The customer signed the contract."],
    "target_lang": "DE",
    "style_profile_id": "3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47"
}'
```

DeepL picks the components that fit the request once the source language is known: the glossaries with a dictionary for the language pair, the style rule list for the target language, and the translation memory whose source language matches the text. A component that doesn't fit is left out without an error, so the same profile works for every language pair it covers. You don't need to set `source_lang`; language detection works as usual.

> [!WARNING]
>
> A style profile replaces the individual customization parameters. A request that combines `style_profile_id` with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, or `translation_memory_threshold` is rejected with `400 Bad Request`. On `/v2/translate`, the same applies to `custom_instructions`.

If the style profile doesn't exist or your account can't access it, `/v2/translate` returns `404 Not Found`. `/v2/document` accepts the upload and reports the error in the [document status](/api-reference/document/check-document-status) with the message `Style profile not found.`.

All `model_type` values are supported. Translation memories linked through a profile use the default matching threshold of 75.

## Set the glossary priority

When two linked glossaries define the same source term, enable `glossary_priority_order_enabled` to make the order of `glossary_ids` decide: the first glossary that defines the term wins. Without it, the order has no effect.

```sh Example request theme={null}
curl -X PATCH https://api.deepl.com/v3/style_profiles/3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "glossary_ids": [
      "4d0a2e1c-6b93-4f7a-8d15-2c6e9a3b7f81",
      "7b2f6d84-3c15-4e90-8a72-d5e1490bc637"
    ],
    "glossary_priority_order_enabled": true
}'
```

## Update a style profile

[`PATCH /v3/style_profiles/{style_profile_id}`](/api-reference/style-profiles/update-style-profile) changes only the fields you send. Each component list you send replaces the linked list in full, so to add a glossary to a profile that already links two, send all three IDs. An empty list unlinks every component of that kind:

```sh Example request theme={null}
curl -X PATCH https://api.deepl.com/v3/style_profiles/3f1c9d0e-7a24-4b58-9c31-8f0e5d2a1b47 \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "translation_memory_ids": []
}'
```

You don't need to update a profile when you delete one of its components. A deleted glossary, style rule list, or translation memory is removed from every profile that links it.

To list or inspect profiles, use [`GET /v3/style_profiles`](/api-reference/style-profiles/list-all-style-profiles) or [`GET /v3/style_profiles/{style_profile_id}`](/api-reference/style-profiles/get-style-profile). [`DELETE /v3/style_profiles/{style_profile_id}`](/api-reference/style-profiles/delete-style-profile) removes the profile but leaves its components in place. Translation requests that still pass the deleted ID fail, so update your integration before deleting.

## Limits

* A style profile links at most one style rule list per target language and one translation memory per source language. Sending two for the same language is rejected with `400 Bad Request`
* The number of style profiles per account depends on your plan. Creating one above the limit is rejected with `456`
* `name` and `industry` are limited to 255 characters, `description` to 1000


# Using Style Rules
Source: https://developers.deepl.com/docs/customize/using-style-rules

Create style rule lists with configured rules and custom instructions, and apply them to translations with the style_id parameter.

Style rules apply a reusable set of formatting and style conventions to your translations. A **style rule list** combines two types of rules:

* **Configured rules**: predefined options for formatting conventions, like time format, number formatting, and punctuation
* **Custom instructions**: your own natural-language instructions for requirements the predefined rules don't cover

Both are applied together during translation. You can build style rule lists in the UI at [deepl.com/custom-rules](https://deepl.com/custom-rules) or manage them programmatically with the [style rules endpoints](/api-reference/style-rules/list-all-style-rules), as shown below.

> [!NOTE]
>
> The Style Rules API is currently available only to Pro API subscribers.

## Create a style rule list

Send `POST /v3/style_rules` a name, the target `language` the rules apply to, and the rules themselves:

```sh Example request theme={null}
curl -X POST https://api.deepl.com/v3/style_rules \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Technical Documentation Rules",
    "language": "en",
    "configured_rules": {
      "dates_and_times": {
        "calendar_era": "use_bc_and_ad"
      },
      "punctuation": {
        "periods_in_academic_degrees": "do_not_use"
      }
    },
    "custom_instructions": [
      {
        "label": "Tone instruction",
        "prompt": "Use a friendly, diplomatic tone",
        "source_language": "en"
      }
    ]
}'
```

```json Example response theme={null}
{
  "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
  "name": "Technical Documentation Rules",
  "creation_time": "2024-10-01T12:34:56Z",
  "updated_time": "2024-10-01T12:34:56Z",
  "language": "en",
  "version": 1,
  "configured_rules": {
    "dates_and_times": {
      "calendar_era": "use_bc_and_ad"
    },
    "punctuation": {
      "periods_in_academic_degrees": "do_not_use"
    }
  },
  "custom_instructions": [
    {
      "id": "68fdb803-c013-4e67-b62e-1aad0ab519cd",
      "label": "Tone instruction",
      "prompt": "Use a friendly, diplomatic tone",
      "source_language": "en"
    }
  ]
}
```

The `version` field increments each time the list is modified, so you can track changes to your style rules. See the [endpoint reference](/api-reference/style-rules/create-style-rule) for all available configured rule categories and options, and the [custom instructions guide](/docs/customize/custom-instructions) for how to write instructions that work well and which kinds of changes they're suited for.

## Apply style rules to a translation

Pass the list's `style_id` in a [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) request. The target language of the request has to match the style rule list's `language`:

```sh Example request theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": ["Das Treffen ist um 15:00 Uhr"],
    "source_lang": "DE",
    "target_lang": "EN",
    "style_id": "a74d88fb-ed2a-4943-a664-a4512398b994"
}'
```

All `model_type` values are supported with style rules. Style rules apply to root languages, so a list with `language: "en"` works for `EN-US` and `EN-GB` targets alike; see [How to Apply Customizations to Language Variants](/docs/customize/customizations-for-variants).

## Update a style rule list

As with glossaries, the update methods have different scopes:

* [`PATCH /v3/style_rules/{style_id}`](/api-reference/style-rules/update-style-rule) updates the list's name
* [`PUT /v3/style_rules/{style_id}/configured_rules`](/api-reference/style-rules/update-configured-rules) **replaces all** configured rules; custom instructions are not affected

Custom instructions are managed individually within a list:

* [`POST /v3/style_rules/{style_id}/custom_instructions`](/api-reference/style-rules/create-custom-instruction) adds an instruction
* [`PUT .../custom_instructions/{instruction_id}`](/api-reference/style-rules/update-custom-instruction) replaces one (all fields required)
* [`DELETE .../custom_instructions/{instruction_id}`](/api-reference/style-rules/delete-custom-instruction) removes one

To list or inspect rule lists, use [`GET /v3/style_rules`](/api-reference/style-rules/list-all-style-rules) (add `detailed=true` to include each list's rules and instructions) or [`GET /v3/style_rules/{style_id}`](/api-reference/style-rules/get-style-rule). Deleting a list with [`DELETE /v3/style_rules/{style_id}`](/api-reference/style-rules/delete-style-rule) cannot be undone.

## Limits

* Style rule lists support the target languages listed in [Languages supported](/docs/getting-started/supported-languages)
* There is no limit on the number of configured rules per list
* A list can hold up to 200 custom instructions (this cap may be adjusted per plan tier in the future); each instruction prompt is limited to 300 characters
* If you need more than 200 custom instructions, split your rules across multiple style rule lists for different content types


# Using Translation Memories
Source: https://developers.deepl.com/docs/customize/using-translation-memories

Learn how to retrieve your translation memories and use them in translation requests

## About translation memories

Translation memories store and reuse previously created translations. When you translate with a translation memory, your source text is compared against the translation memory's segments. If a segment is similar enough, the stored translation is applied instead of generating a new one.

## What you'll learn

In this tutorial, we'll retrieve the translation memories on your account, use one in a translation request, and adjust the matching threshold to control how closely source text must match a stored segment.

## Before you begin

You'll need:

* A DeepL API authentication key
* At least one translation memory uploaded to your account via the DeepL UI
* A terminal or HTTP client for making API requests
* Approximately 10 minutes

### Example translation memory

In this tutorial, we'll use a translation memory called "Greetings" that contains German-to-English translations. One of its segments looks like this:

| Source (DE) | Translation (EN) |
| - | - |
| Hallo Welt! | Hello everyone! |

Notice that the translation memory specifies a custom translation — "Hello everyone!" instead of the literal "Hello world!". When we send matching source text to the API with this translation memory, DeepL will reuse the stored translation instead of generating its own.

## Step 1: List your translation memories

First, let's retrieve the translation memories on your account so we can find the one we want to use.

```sh theme={null}
curl -X GET 'https://api.deepl.com/v3/translation_memories' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```

**Expected output:**

```json theme={null}
{
  "translation_memories": [
    {
      "translation_memory_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
      "name": "Greetings",
      "source_language": "de",
      "target_languages": ["en"],
      "segment_count": 42
    }
  ],
  "total_count": 1
}
```

Notice the `translation_memory_id` — this is what we'll pass to the translate endpoint. Also note the `source_language` and `target_languages` fields, which tell us this translation memory translates from German to English.

> [!NOTE]
>
> If you see an empty list, make sure you've uploaded at least one translation memory via the [DeepL translation memory page](https://www.deepl.com/translation-memory).

## Step 2: Translate text with a translation memory

Now let's use that translation memory in a translation request. Add the `translation_memory_id` parameter to your call to the [text translation endpoint](/api-reference/translate/request-translation#body-translation-memory-id).

```sh theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "text": [
    "Hallo Welt!"
  ],
  "target_lang": "EN",
  "translation_memory_id": "a74d88fb-ed2a-4943-a664-a4512398b994"
}'
```

**Expected output:**

```json theme={null}
{
  "translations": [
    {
      "detected_source_language": "DE",
      "text": "Hello everyone!"
    }
  ]
}
```

The result is "Hello everyone!" — the custom translation from our translation memory — rather than the default "Hello world!" that DeepL would produce without it.

Notice that we didn't need to specify `source_lang` — language auto-detection still works when using a translation memory.

## Step 3: Adjust the matching threshold

By default, a stored segment is applied when it matches at least **75%** of the source text. This means translation memory segments can match even when the source text isn't identical — which is useful for catching typos and minor variations. The lowest supported threshold is 50, and a lower value is treated as 50.

Let's see this in action. Imagine we make a typo and send "Halloo Welt!" instead of "Hallo Welt!":

```sh theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "text": [
    "Halloo Welt!"
  ],
  "target_lang": "EN",
  "translation_memory_id": "a74d88fb-ed2a-4943-a664-a4512398b994"
}'
```

**Expected output:**

```json theme={null}
{
  "translations": [
    {
      "detected_source_language": "DE",
      "text": "Hello everyone!"
    }
  ]
}
```

With the default threshold of `75`, "Halloo Welt!" is close enough to "Hallo Welt!" that the translation memory segment still applies, and we get our custom translation "Hello everyone!".

Now let's raise the threshold to `100` so only exact matches are used:

```sh theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "text": [
    "Halloo Welt!"
  ],
  "target_lang": "EN",
  "translation_memory_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
  "translation_memory_threshold": 100
}'
```

**Expected output:**

```json theme={null}
{
  "translations": [
    {
      "detected_source_language": "DE",
      "text": "Hello world!"
    }
  ]
}
```

With a threshold of `100`, "Halloo Welt!" is no longer an exact match for "Hallo Welt!", so the translation memory segment is not applied. DeepL falls back to its default translation: "Hello world!".

## What you've accomplished

You've learned how to:

* Retrieve the translation memories on your account
* Use a translation memory in a translation request
* Control the matching threshold to tune how closely source text must match a stored segment

## See also

* [List translation memories](/api-reference/translation-memory/list-translation-memories) — API reference
* [Text translation endpoint](/api-reference/translate/request-translation#body-translation-memory-id) — `translation_memory_id` and `translation_memory_threshold` parameter reference
* [Supported languages](/docs/getting-started/supported-languages) — check which languages support translation memories


# About
Source: https://developers.deepl.com/docs/getting-started/about

What the DeepL API offers, the use cases it covers, and which product to reach for when adding translation to your app.

![Animated DeepL banner](https://mintcdn.com/deepl-c950b784/OnHfwyeOjDg0aJdt/_assets/images/intro/banner.gif?s=4a272b8f97f5330ea68a5a41fb3b8a59)

The DeepL API provides programmatic access to DeepL’s language AI technology, making it possible to bring high quality translation capabilities directly to your websites and applications.

## Common use cases for the DeepL API:

* **Website translation**: Localize websites and expand to new markets efficiently and at scale—even in sectors like e-commerce and news media with a large catalog of dynamic content.
* **Company communications**: Integrate DeepL’s translation technology into your company’s systems such as Confluence and SharePoint. Enable your global teams to communicate seamlessly and with [maximum data security](https://www.deepl.com/pro-data-security/).
* **Building multilingual products**: Translate chat conversations to connect users across language barriers in real time. Localize comments and product reviews with the click of a button. Make translation one of your differentiating features—however you imagine it.

In addition, many leading computer-assisted translation (CAT) tool providers have [integrated DeepL’s technology into their software](https://support.deepl.com/hc/articles/360019358599-CAT-tools-supported). This lets translators benefit from DeepL’s high-quality neural translations within their favorite translation tool. If you would like to develop a DeepL plugin for your CAT tool, [please contact us at here](https://support.deepl.com/hc/en-us/requests/new).

## Why the DeepL API?

* **High-quality text and document translations**: DeepL [consistently outperforms the competition](https://www.deepl.com/quality.html) in translation quality, and not only for text translation. The API also supports [many document, publishing, and localization formats](/api-reference/document/upload-and-translate-a-document) including DOCX, PPTX, XLSX, PDF, HTML, IDML, XLIFF, XML, JSON, DITA, and MIF, plus beta support for XLSM, SCORM, WebVTT, YAML, Markdown, RESX, ODT, RTF, and more.
* **Maximum data security**: With DeepL API paid plans, texts aren’t saved on persistent storage and aren’t used to train our models. And DeepL adheres strictly to EU data protection laws and ISO 27001. [Learn more about data security at DeepL](https://www.deepl.com/pro-data-security/).
* **Customization with glossaries**: [Specify your own translations for words and phrases](/docs/customize/managing-glossaries), and customize your translations consistently and at scale.

To access the DeepL API, [sign up for a plan](https://www.deepl.com/en/pro#api).


# SDKs
Source: https://developers.deepl.com/docs/getting-started/client-libraries

Using your favorite programming language with the DeepL API

## Overview

You can use many popular programming languages to access the DeepL API.

DeepL enables this through six official client libraries. [Hosted on GitHub](https://github.com/DeepL), these client libraries handle API requests and help parse responses so you can focus on building your application. For example, [the JavaScript library's `translateDocument()` function](https://github.com/DeepL/deepl-node?tab=readme-ov-file#translating-documents) handles the document translation workflow - uploading a document, polling for completion, and downloading the result.

This documentation site frequently includes code samples in the six programming languages DeepL supports and maintains. But for complete information, setup instructions, installation steps, and code samples, see these GitHub repositories:

> **[DeepL C# Library](https://www.github.com/deeplcom/deepl-dotnet)**
>
> deeplcom\deepl-dotnet

> **[DeepL Java Library](https://www.github.com/deeplcom/deepl-java)**
>
> deeplcom\deepl-java

> **[DeepL JavaScript Library](https://www.github.com/deeplcom/deepl-node)**
>
> deeplcom\deepl-node

> **[DeepL PHP Library](https://www.github.com/deeplcom/deepl-php)**
>
> deeplcom\deepl-php

> **[DeepL Python Library](https://www.github.com/deeplcom/deepl-python)**
>
> deeplcom\deepl-python

> **[DeepL Ruby Library](https://www.github.com/deeplcom/deepl-rb)**
>
> deeplcom\deepl-rb

## Community-created client libraries

The DeepL community [maintains client libraries](https://github.com/DeepL/awesome-deepl?tab=readme-ov-file#community-libraries--sdks) for other languages, including [Dart](https://github.com/komape/deepl_dart), [Go](https://github.com/candy12t/go-deepl), [Rust](https://github.com/Avimitin/deepl-rs), and [Kotlin](https://github.com/SimplyMika/DeeplKt).

## Next steps

Now that you've found your client library, here are a few ways to keep learning about the DeepL API:

* try sample requests [in our playground](https://developers.deepl.com/api-reference/translate/request-translation?playground=open)
* [Translate Text Quickstart](/docs/translate/translate-text-quickstart) - send your first text translation requests
* [Translate Documents Quickstart](/docs/translate/translate-documents-quickstart) - translate a complete file, formatting included


# DeepL CLI
Source: https://developers.deepl.com/docs/getting-started/deepl-cli

Install and use the DeepL CLI to translate text, documents, and more from your terminal.

**This page shows you:**

* How to install the DeepL CLI from source
* How to authenticate and run your first translation
* What commands are available for translation, writing, voice, and more

The [DeepL CLI](https://github.com/DeepL/deepl-cli) is an open-source (MIT license) command-line tool for interacting with the DeepL API. It covers text translation, document translation, writing enhancement, voice translation, glossary management, and admin operations — all from your terminal.

## Installation

> [!NOTE]
>
> The CLI requires [Node.js](https://nodejs.org/) (v18+) and build tools for native compilation:
>
> * **macOS**: Xcode Command Line Tools (`xcode-select --install`)
> * **Linux**: `python3`, `make`, `gcc` (`apt install python3 make gcc g++`)
> * **Windows**: Visual Studio Build Tools

```bash theme={null}
git clone https://github.com/DeepL/deepl-cli.git
cd deepl-cli
npm install
npm run build
npm link

deepl --version
```

## Quick start

### 1. Set up authentication

Use the interactive setup wizard:

```bash theme={null}
deepl init
```

Or set your API key directly:

```bash theme={null}
deepl auth set-key YOUR_API_KEY
```

Or use an environment variable:

```bash theme={null}
export DEEPL_API_KEY=YOUR_API_KEY
```

### 2. Translate text

```bash theme={null}
deepl translate "Hello, world!" --to es
# ¡Hola, mundo!
```

### 3. Enhance your writing

```bash theme={null}
deepl write "Their going to the stor tommorow" --lang en-us
# They're going to the store tomorrow.
```

## Key capabilities

| Command | Description |
| - | - |
| `deepl translate` | Translate text with support for formality, context, and custom instructions |
| `deepl translate --file` | Translate text files while preserving code blocks and formatting |
| `deepl document` | Translate documents (PDF, DOCX, PPTX, XLSX) with format preservation |
| `deepl write` | Enhance grammar and style via DeepL Write |
| `deepl voice` | Stream real-time speech translation via WebSocket |
| `deepl watch` | Monitor files and auto-translate on change |
| `deepl glossary` | Create, list, and manage glossaries |
| `deepl admin` | Manage API keys, usage limits, and team access |
| `deepl usage` | Check API usage and character quotas |
| `deepl config` | Configure defaults (target language, formality, model) |

## Usage examples

### Translate with context and formality

```bash theme={null}
deepl translate "Thank you for your patience" --to de --formality more \
  --context "Customer support email to a long-standing client"
```

### Translate a document

```bash theme={null}
deepl document translate report.pdf --to fr --output report-fr.pdf
```

### Batch translate a directory

```bash theme={null}
deepl translate --file src/locales/en/ --to de,fr,es --output src/locales/
```

### Watch mode for development

```bash theme={null}
deepl watch ./content/en --to de,fr --output ./content/
```

### Git hooks integration

Automatically translate changed files before each commit:

```bash theme={null}
deepl hooks install --pre-commit --languages de,fr
```

## Developer workflow features

* Local SQLite cache with LRU eviction avoids redundant API calls
* Monitor billed characters for budget planning with `deepl usage`
* Use `--quiet` and `--no-input` flags for CI/CD pipelines
* Generate shell completions for bash, zsh, fish, and PowerShell

## Further reading

* [DeepL CLI on GitHub](https://github.com/DeepL/deepl-cli) — full documentation, changelog, and source code
* [DeepL API authentication](/docs/getting-started/auth) — set up your API key
* [Client libraries](/docs/getting-started/client-libraries) — official SDKs for six languages


# Docs MCP Server
Source: https://developers.deepl.com/docs/getting-started/docs-mcp-server

Connect your AI tools to the DeepL developer documentation for source-grounded answers about the DeepL API.

**This page shows you:**

* What the DeepL Docs MCP Server is and how it differs from [DeepL Remote MCP](/docs/mcp)
* How to connect it to Claude, Cursor, VS Code, and other AI tools

The DeepL developer documentation site exposes a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server at `https://developers.deepl.com/mcp`. This lets AI tools search and read our documentation directly, so they can give you accurate, up-to-date answers about the DeepL API without relying on training data.

> [!NOTE]
>
> This is different from [DeepL Remote MCP](/docs/mcp), which lets AI agents *use* DeepL (translate text and documents, manage glossaries, etc.). The Docs MCP Server provides read-only access to the documentation itself.

## What it provides

When connected, your AI tool gets two capabilities:

* **Search**: Find relevant documentation pages by keyword, returning snippets with titles and links
* **Read**: Navigate and read full pages from the documentation site

Your AI tool decides when to use each capability based on the conversation context. For example, if you ask "How do I use glossaries with the DeepL API?", the tool can search the docs, pull up the relevant pages, and give you an answer grounded in the actual documentation.

## Setup

**Claude Desktop**

1. Open Claude Desktop and go to **Settings > Connectors**
2. Click **Add custom connector**
3. Enter a name (e.g., "DeepL Docs") and the URL: `https://developers.deepl.com/mcp`
4. In any chat, click the attachments icon and select the connector to activate it

**Claude Code**

Run this command to add the server:

```bash theme={null}
claude mcp add --transport http deepl-docs https://developers.deepl.com/mcp
```

Claude Code can now search and reference DeepL documentation during your sessions.

**Cursor**

Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`), search for "Open MCP Settings", and add the following to your `mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "deepl-docs": {
      "url": "https://developers.deepl.com/mcp"
    }
  }
}
```

**VS Code**

Create a `.vscode/mcp.json` file in your project root:

```json theme={null}
{
  "servers": {
    "deepl-docs": {
      "type": "http",
      "url": "https://developers.deepl.com/mcp"
    }
  }
}
```

**Other MCP clients**

Any MCP-compatible client can connect using the server URL:

```
https://developers.deepl.com/mcp
```

Refer to your client's documentation for how to add remote MCP servers.

No API key or authentication is required.

## Example prompts

Once connected, try asking your AI tool questions like:

* "How do I translate a document using the DeepL API?"
* "What parameters does the text translation endpoint accept?"
* "How do glossaries work in DeepL?"
* "What are the rate limits for the DeepL API?"

The AI tool will search the documentation and return answers with references to specific pages.


# Quickstart
Source: https://developers.deepl.com/docs/getting-started/quickstart

Get a DeepL API key and send your first translation request, with examples in curl and every official client library.

## Get an API key and get started

New user? Follow these quick steps to get started with the DeepL API.

### 1. Sign up for the API

Visit [our plans page](https://www.deepl.com/pro-api#api-pricing), choose a plan, and sign up.

If you already have a DeepL Translator account, you will need to log out and [create a new account](https://support.deepl.com/hc/articles/360019358999-Change-plan).

### 2. Test your API key with a request

Find your API key [here](https://www.deepl.com/your-account/keys).
Then try making a simple translation request.

**HTTP Request**

> [!TIP]
>
> If you chose a free API plan, replace `https://api.deepl.com` with `https://api-free.deepl.com`.

```http Sample request theme={null}
POST /v2/translate HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey] 
User-Agent: YourApp/1.2.3
Content-Length: 45
Content-Type: application/json

{"text":["Hello, world!"],"target_lang":"DE"}
```

```json Sample response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Hallo, Welt!"
    }
  ]
}
```

**cURL**

> [!TIP]
>
> If you chose a free API plan, replace `https://api.deepl.com` with `https://api-free.deepl.com`.

```sh Set the API key theme={null}
export API_KEY={YOUR_API_KEY}
```

```sh Sample request theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": ["Hello world!"], 
    "target_lang": "DE"
}'
```

```json Sample response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Hallo, Welt!"
    }
  ]
}
```

**Python**

```sh Install client library theme={null}
pip install deepl
```

```py Sample request theme={null}
import deepl

auth_key = "{YOUR_API_KEY}" # replace with your key
deepl_client = deepl.DeepLClient(auth_key)

result = deepl_client.translate_text("Hello, world!", target_lang="DE")
print(result.text)
```

```text Sample output theme={null}
Hallo, Welt!
```

> [!TIP]
>
> In production code, it's safer to store your API key in an environment variable.

**JavaScript**

```sh Install client library theme={null}
npm install deepl-node
```

```javascript Sample request theme={null}
import * as deepl from 'deepl-node';

const authKey = "{YOUR_API_KEY}"; // replace with your key
const deeplClient = new deepl.DeepLClient(authKey);

(async () => {
    const result = await deeplClient.translateText('Hello, world!', null, 'de');
    console.log(result.text);
})();
```

```text Sample output theme={null}
Hallo, Welt!
```

> [!TIP]
>
> In production code, it's safer to store your API key in an environment variable.

**PHP**

```sh Install client library theme={null}
composer require deeplcom/deepl-php
```

```php Sample request theme={null}
require_once 'vendor/autoload.php';
use DeepL\Client;

$authKey = "{YOUR_API_KEY}"; // replace with your key
$deeplClient = new DeepL\DeepLClient($authKey);

$result = $deeplClient->translateText('Hello, world!', null, 'de');
echo $result->text;
```

```text Sample output theme={null}
Hallo, Welt!
```

> [!TIP]
>
> In production code, it's safer to store your API key in an environment variable.

**C#**

```sh Install client library theme={null}
dotnet add package DeepL.net
```

```csharp Sample request theme={null}
using DeepL; // this imports the DeepL namespace. Use the code below in your main program.

var authKey = "{YOUR_API_KEY}"; // replace with your key
var client = new DeepLClient(authKey);

var translatedText = await client.TranslateTextAsync(
    "Hello, world!",
    null,
    LanguageCode.German);
Console.WriteLine(translatedText);
```

```text Sample output theme={null}
Hallo, Welt!
```

> [!TIP]
>
> In production code, it's safer to store your API key in an environment variable.

**Java**

```java Install client library theme={null}
// For instructions on installing the DeepL Java library,
// see https://github.com/DeepL/deepl-java?tab=readme-ov-file#installation
```

```java Sample request theme={null}
import com.deepl.api.*;

public class Main {
    public static void main(String[] args) throws DeepLException, InterruptedException {
        String authKey = "{YOUR_API_KEY}"; // replace with your key
        DeepLClient client = new DeepLClient(authKey);

        TextResult result = client.translateText("Hello, world!", null, "de");
        System.out.println(result.getText());
    }
}
```

```text Sample output theme={null}
Hallo, Welt!
```

> [!TIP]
>
> In production code, it's safer to store your API key in an environment variable.

**Ruby**

```sh Install client library theme={null}
gem install deepl-rb
```

```ruby Sample request theme={null}
require 'deepl'

DeepL.configure do |config|
    config.auth_key = '{YOUR_API_KEY}' # replace with your key
end

translation = DeepL.translate 'Hello, world!', nil, 'de'
puts translation.text
```

```text Sample output theme={null}
Hallo, Welt!
```

> [!TIP]
>
> In production code, it's safer to store your API key in an environment variable.

### 3. Keep building

Pick the product you want to integrate:

> **[Translate](/docs/translate/overview)**
>
> Translate text strings and complete documents, with quickstarts for both.

> **[Customize](/docs/customize/overview)**
>
> Tailor translations to your domain with glossaries, style rules, and translation memories.

> **[Voice](/docs/voice/overview)**
>
> Transcribe and translate spoken audio in real time, starting with the Real-Time Voice Quickstart.

> **[Admin](/docs/admin/overview)**
>
> Manage API keys, permissions, and usage across your organization, in the account UI or via the Admin API.

[Our official client libraries](/docs/getting-started/client-libraries) wrap the API for Python, JavaScript, PHP, .NET, Java, and Ruby, and the community maintains [libraries for more languages](https://github.com/DeepL/awesome-deepl?tab=readme-ov-file#community-libraries--sdks), including Dart, Go, and Rust.

## Keep exploring

* [**Cookbook**](/docs/learning-how-tos/cookbook) - Short tutorials, examples, projects, and use cases
* [**Guides**](/docs/learning-how-tos/examples-and-guides) - In-depth explanations for API features and real-world applications
* [**Docs MCP Server**](/docs/getting-started/docs-mcp-server) - Connect your AI tools to this documentation for source-grounded answers

## Community and Support

> Support Center
>
> [Open](https://support.deepl.com/)

> Discord Community
>
> [Open](https://discord.gg/deepl)

> API Status Page
>
> [Open](https://status.deepl.com/?tab=api)

> DeepL Status Page (all services)
>
> [Open](https://status.deepl.com/)

> Release Notes
>
> [Open](/docs/resources/roadmap-and-release-notes)


# Regional API Endpoints
Source: https://developers.deepl.com/docs/getting-started/regional-endpoints

Reference documentation for DeepL's regional API endpoints, including endpoint URLs, configuration, and technical specifications.

DeepL offers regional API endpoints that process and store data within specific geographic regions. Regional endpoints provide the same API functionality as the standard endpoint, with data processing occurring in data centers located in specific regions. These endpoints help organizations meet data residency and compliance requirements, and can also reduce latency for users in specific geographic regions.

> [!WARNING]
>
> Regional endpoints are only available to customers who have signed a regional deployment addendum. Without a signed addendum, requests to regional endpoints return a 403 error. Contact your account manager or [reach out to our sales team](https://www.deepl.com/contact-us) to discuss access.

## Endpoint URLs

DeepL currently offers the following regional endpoints:

| **Region** | **Endpoint URL** |
| - | - |
| **United States** | `https://api-us.deepl.com` |
| **Japan** | `https://api-jp.deepl.com` |
| **European Union (default)** | `https://api.deepl.com` |

***

## Configuration

Regional endpoints are configured by specifying the endpoint URL in the API client. The standard endpoint URL (`https://api.deepl.com`) is replaced with the regional endpoint URL (`https://api-us.deepl.com` or `https://api-jp.deepl.com`).

**cURL**

```bash theme={null}
# Standard endpoint
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "text": ["Hello, world!"],
  "target_lang": "DE"
}'

# US regional endpoint
curl -X POST 'https://api-us.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "text": ["Hello, world!"],
  "target_lang": "DE"
}'
```

**Python**

The Python client library accepts a `server_url` parameter:

```python theme={null}
import deepl

# Standard endpoint
translator = deepl.Translator("[yourAuthKey]")

# US regional endpoint
translator = deepl.Translator(
    "[yourAuthKey]",
    server_url="https://api-us.deepl.com"
)

# Usage remains identical
result = translator.translate_text("Hello, world!", target_lang="DE")
print(result.text)
```

**Node.js**

The Node.js client library accepts a `serverUrl` option:

```javascript theme={null}
const deepl = require('deepl-node');

// Standard endpoint
const translator = new deepl.Translator('[yourAuthKey]');

// US regional endpoint
const translator = new deepl.Translator(
    '[yourAuthKey]',
    { serverUrl: 'https://api-us.deepl.com' }
);

// Usage remains identical
(async () => {
    const result = await translator.translateText('Hello, world!', null, 'de');
    console.log(result.text);
})();
```

**Java**

The Java client library accepts a `TranslatorOptions` object with `setServerUrl()` method:

```java theme={null}
import com.deepl.api.*;

// Standard endpoint
Translator translator = new Translator("[yourAuthKey]");

// US regional endpoint
TranslatorOptions options = new TranslatorOptions()
    .setServerUrl("https://api-us.deepl.com");
Translator translator = new Translator("[yourAuthKey]", options);

// Usage remains identical
TextResult result = translator.translateText("Hello, world!", null, "de");
System.out.println(result.getText());
```

**C# / .NET**

The .NET client library accepts a `TranslatorOptions` object with `ServerUrl` property:

```csharp theme={null}
using DeepL;

// Standard endpoint
var translator = new Translator("[yourAuthKey]");

// US regional endpoint
var translator = new Translator(
    "[yourAuthKey]",
    new TranslatorOptions { ServerUrl = "https://api-us.deepl.com" }
);

// Usage remains identical
var result = await translator.TranslateTextAsync("Hello, world!", null, "de");
Console.WriteLine(result.Text);
```

**PHP**

The PHP client library accepts a `server_url` option in the options array:

```php theme={null}
use DeepL\Translator;

// Standard endpoint
$translator = new Translator('[yourAuthKey]');

// US regional endpoint
$translator = new Translator(
    '[yourAuthKey]',
    ['server_url' => 'https://api-us.deepl.com']
);

// Usage remains identical
$result = $translator->translateText('Hello, world!', null, 'de');
echo $result->text;
```

***

## Technical specifications

### Access requirements

Regional endpoints require activation through a regional deployment addendum. Requests to regional endpoints without activation return a 403 error (`Your account is denied access`). Contact your account manager or [reach out to our sales team](https://www.deepl.com/contact-us) to activate regional endpoints for your account.

While API keys are not region-specific, each DeepL account is restricted to a single region. Your keys work only with the regional endpoint your account is assigned to.

### API compatibility

Regional endpoints support all DeepL API functionality except the Admin Analytics API. These endpoints are only available on the standard `api.deepl.com` endpoint.

### Glossaries and style rules

Glossaries and style rules are unique to each of DeepL's regional data centers and are not shared between them. Glossaries and style rules created via the API on one regional endpoint (e.g., `api-us.deepl.com`) are only accessible from that same endpoint.

Additionally, the DeepL web UI (at [deepl.com](https://www.deepl.com)) currently only accesses the European Union data center. Glossaries and style rules created in the UI are only accessible via the standard `api.deepl.com` endpoint, not regional endpoints like `api-us.deepl.com` or `api-jp.deepl.com`.

For more details, see the [Style rules documentation](/docs/customize/using-style-rules).

***

## Related documentation

* [Client libraries](/docs/getting-started/client-libraries) - Language-specific client library documentation and configuration
* [Authentication and access](/docs/getting-started/auth) - API authentication methods and security best practices
* [Text translation](/api-reference/translate/request-translation) - Text translation API reference
* [Admin API](/docs/admin/overview) - Programmatic API key management for enterprise administrators


# Languages supported
Source: https://developers.deepl.com/docs/getting-started/supported-languages

Every language the DeepL API supports, and how to retrieve the list programmatically with feature availability.

The DeepL API supports the following languages. These can also be retrieved programmatically via the [`/v3/languages` endpoint](/docs/languages/using-the-languages-api), which returns language support per resource along with feature availability (e.g. formality, glossary, auto-detection). The legacy [`/v2/languages` endpoint](/api-reference/languages/retrieve-supported-languages) is also available but deprecated.## API Supported Languages

Filter by feature



                

Showing  of  languages



            
            

\<table aria-label="DeepL API supported languages and features"><thead><tr><th role="columnheader button" tabIndex={0}>Code</th>
                            \<th role="columnheader button" tabIndex={0}>Language</th>
                            \<th>Features</th></tr></thead>
                    \<tbody /></table>



# Postman
Source: https://developers.deepl.com/docs/getting-started/test-your-api-requests-with-postman

Use our official Postman collection to get familiar with and test the DeepL API.

Whether you are just getting started with DeepL API, or you already have an integration running in a production environment, sometimes it's a great idea to have a safe test environment to try things out first.

For convenience, we've created a Postman collection that mirrors the DeepL API functionality and lets you test your API in a structured environment. For more information about Postman, [check out their overview](https://learning.postman.com/docs/introduction/overview/).

![](https://mintcdn.com/deepl-c950b784/OnHfwyeOjDg0aJdt/_assets/images/Request_Translation___DeepL_API_Developers___Postman_API_Network.png?fit=max\&auto=format\&n=OnHfwyeOjDg0aJdt\&q=85\&s=cb08894802aec4926de721e6eb5df23c)

To get started, [sign up for a developer account at deepl.com](https://www.deepl.com/pro/change-plan#developer) and get your authentication key from [your account page](https://www.deepl.com/your-account/keys).

Click the button below to fork the DeepL API collection into your own Postman workspace:

[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/27518486-e9e2969d-d589-4d3d-9df6-cc514cf3ee5e?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D27518486-e9e2969d-d589-4d3d-9df6-cc514cf3ee5e%26entityType%3Dcollection%26workspaceId%3D48a52b53-0654-484b-861d-ae228857c2f6)

In your forked collection, select the relevant `baseUrl` variable depending on your subscription (`https://api.deepl.com/v2` for **Pro**, `https://api-free.deepl.com/v2` for **Free**).

The `apiKey` variable will be `DeepL-Auth-Key yourDeepLApiKey`. Change `yourDeepLApiKey` for your own key (leaving the `DeepL-Auth-Key` in front) and you're ready to go!


# Migrating from v2/languages
Source: https://developers.deepl.com/docs/languages/migrating-from-v2-languages

How to migrate from the v2/languages endpoint to the v3/languages endpoints.

This page covers the differences between the `/v2/languages` endpoint and the v3 endpoints, and how to update your integration.

> [!WARNING]
>
> Only `GET` requests are supported on the v3 endpoints. Unlike `/v2/languages`, POST is not supported.

## What changed

### Single endpoint for source and target

v2 uses a single endpoint with a `type` query parameter to distinguish source from target:

```
GET /v2/languages?type=source
GET /v2/languages?type=target
```

v3 uses a single endpoint that returns all languages for a resource, with each language indicating whether it is
usable as a source, a target, or both:

```
GET /v3/languages?resource=translate_text
```

### New resource identifiers

v2 languages are implicitly tied to text and document translation. v3 introduces an explicit `resource` parameter that applies across all DeepL API resources:

| **v2** | **v3 `resource` value** |
| - | - |
| *(implicit, text/document translation only)* | `translate_text` |
| *(implicit, text/document translation only)* | `translate_document` |
| *(separate `/v2/glossary-language-pairs` endpoint)* | `glossary` |
| *(not supported)* | `voice` |
| *(not supported)* | `write` |

The v3 endpoints replace both `/v2/languages` and `/v2/glossary-language-pairs`.

### Features instead of `supports_formality`

v2 target languages include a boolean `supports_formality` field. v3 replaces this with a `features` object that covers additional capabilities per resource:

| **v2 field** | **v3 equivalent** |
| - | - |
| `"supports_formality": true` | `"formality"` key present in the language's `features` object |

For example, querying languages for text translation:

```sh theme={null}
curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```

```json Example response (truncated) theme={null}
[
  {
    "lang": "de",
    "name": "German",
    "usable_as_source": true,
    "usable_as_target": true,
    "status": "stable",
    "features": {
      "formality": {"status": "stable"},
      "tag_handling": {"status": "stable"},
      "glossary": {"status": "stable"}
    }
  },
  {
    "lang": "en-US",
    "name": "English (American)",
    "usable_as_source": false,
    "usable_as_target": true,
    "status": "stable",
    "features": {
      "tag_handling": {"status": "stable"},
      "glossary": {"status": "stable"}
    }
  }
]
```

The response indicates German supports `formality` (key present in `features`), but English (American) does not (key absent).

See the [overview](/docs/languages/using-the-languages-api) for the full list of features per resource.

### Response field names

| **v2 field** | **v3 field** |
| - | - |
| `language` | `lang` |
| `name` | `name` *(unchanged)* |
| `supports_formality` | `"formality"` key in `features` object |
| *(not present)* | `status` |

### Language code casing

v2 returned language codes in non-standard casing (e.g. `EN-US`, `ZH-HANT`). v3 returns codes compliant with BCP 47: lowercase base language (`en`, `de`), uppercase region subtag (`en-US`, `pt-BR`), and title-case script subtag (`zh-Hant`).

DeepL accepts language codes case-insensitively as input across all endpoints. However, if your integration stores or compares codes returned by `/v2/languages`, update those comparisons to be case-insensitive or to expect the new casing.

## Migrating glossary language pair queries

If you currently use `/v2/glossary-language-pairs` to discover which language pairs are supported for glossaries, use one of the following:

* `GET /v3/languages?resource=glossary` to check which languages support glossary management (i.e. creating a glossary for that language). Filter by `usable_as_source` and `usable_as_target` as needed. Any combination of a valid source and target language is a supported glossary language pair.
* `GET /v3/languages?resource=translate_text` to check which languages support using a glossary during text translation. Languages with a `"glossary"` key in their `features` object support the `glossary_id` parameter on the translate endpoint.
* Similarly, use `resource=translate_document` to check glossary support for document translation.


# Using the Languages API
Source: https://developers.deepl.com/docs/languages/using-the-languages-api

Retrieve supported language and feature data across all DeepL API resources with the v3/languages endpoints, with pseudocode examples for common lookup patterns.

The `/v3/languages` endpoints tell you which languages each DeepL API resource supports and which optional features (formality, glossaries, tag handling, and more) are available per language. Use them to drive language dropdowns, feature toggles, and validation in your integration instead of hardcoding language lists.

> [!NOTE]
>
> The `/v3/languages` endpoints replace the deprecated `/v2/languages` and `/v2/glossary-language-pairs` endpoints.
> If you're currently using either, see the [migration guide](/docs/languages/migrating-from-v2-languages) for
> differences and code examples.

For the auto-generated API specs, for use with API clients and code generation tools, see:

* [Retrieve languages](/api-reference/languages/retrieve-languages-by-resource)
* [Retrieve resources](/api-reference/languages/retrieve-resources)

To understand how these endpoints are updated when DeepL adds translation support for a new language or language variant, see [the language release process](/docs/resources/language-release-process).

## Resources list

To retrieve language support, decide which DeepL resource you're building for, then call `GET /v3/languages` with
the appropriate `resource` value. The `resource` parameter is required and identifies which DeepL API resource you
are querying language support for:

| **Value** | **Description** |
| - | - |
| `translate_text` | Text translation via the `/v2/translate` endpoint |
| `translate_document` | Document translation via the `/v2/document` endpoint |
| `voice` | Speech transcription and translation via the `/v3/voice` endpoints |
| `write` | Text improvement via the `/v2/write` endpoints |
| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
| `style_rules` | Style rules management via the `/v3/style_rules` endpoints |

> [!NOTE]
>
> `glossary` and `style_rules` are resource values indicating glossaries and style rules that can be created for that
> language, and managed via the glossary and style rules management endpoints.
>
> Support for glossaries and style rules within specific resources (for example text translation) is indicated by the
> `glossary` and `style_rules` feature value, explained in a later section.

## Basic example

Each language in the response includes a `features` object indicating which optional capabilities are available for that
language — see the [Resource features](#resource-features) section below for details.

The examples below use our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update
your requests to use `https://api-free.deepl.com` instead.

The following example responses are truncated; the full API responses can include over 100 languages.

**cURL**

```sh Example request: languages for text translation theme={null}
curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```

**HTTP Request**

```http Example request: languages for text translation theme={null}
GET /v3/languages?resource=translate_text HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
```

```json Example response theme={null}
[
  {
    "lang": "de",
    "name": "German",
    "usable_as_source": true,
    "usable_as_target": true,
    "status": "stable",
    "features": {
      "formality": {"status": "stable"},
      "tag_handling": {"status": "stable"},
      "glossary": {"status": "stable"}
    }
  },
  {
    "lang": "en",
    "name": "English",
    "usable_as_source": true,
    "usable_as_target": false,
    "status": "stable",
    "features": {
      "tag_handling": {"status": "stable"},
      "glossary": {"status": "stable"}
    }
  },
  {
    "lang": "en-US",
    "name": "English (American)",
    "usable_as_source": false,
    "usable_as_target": true,
    "status": "stable",
    "features": {
      "tag_handling": {"status": "stable"},
      "glossary": {"status": "stable"}
    }
  }
]
```

## Language codes

Language codes in the `lang` field follow [BCP 47](https://www.rfc-editor.org/rfc/rfc5646). The base language
subtag is always present; script, region, and variant subtags are included where needed to distinguish variants. See [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details.

## Resource features

Each language object includes a `features` object indicating which optional capabilities are supported for that language
with the requested resource. Each key is a feature name; the value is an object with at least a `status` field.

To check whether a feature is supported, check that the key exists in the `features` object:

```text theme={null}
// Feature supported:
"features": { "formality": { "status": "stable" } }

// Feature not supported:
"features": {}
```

To use a feature, one or both languages in the pair must support it. For example, for text translation:

* **Target-only**: `formality` only needs to be supported by the target language. Check that `"formality"` is
  a key in the target language's `features` object.
* **Source-and-target**: `tag_handling` and `glossary` must be supported by both languages. Check that the
  feature key is present in *both* the source and target language's `features` objects.
* **Source-only**: `auto_detection` only needs to be supported by the source language.

In the documentation for API features that are supported for only a subset of languages, we specify
which language feature key to check, and whether to check the source language, target language, or both.

### Resource feature reference

The table below lists all feature keys that can appear in a language's `features` object.

| **Feature** | **Check language support on** | **Resources** | **Description** |
| - | - | - | - |
| `auto_detection` | source | `translate_text`, `translate_document`, `voice`, `write` | Language can be automatically detected as the source language. |
| `style_rules` | target | `translate_text` | Language supports style rules that guide how DeepL translates text. Used with the `custom_instructions` and `style_id` parameters on the translate endpoint. |
| `formality` | target | `translate_text`, `translate_document`, `voice` | Language supports formality control — adjusting the output to use formal or informal register. |
| `glossary` | source + target | `translate_text`, `translate_document`, `voice` | Language can be used with a glossary to enforce specific terminology. Both the source and target language must support this for a glossary to be usable with a given pair. |
| `tag_handling` | source + target | `translate_text`, `translate_document` | Language supports tag-aware translation, preserving markup structure (e.g. HTML, XML) in the output. |
| `transcription` | source | `voice` | Language supports transcription from audio to text. |
| `translated_speech` | target | `voice` | Language supports conversion from translated text to audio output. |
| `spoken_terms` | source | `voice` | Language supports spoken terms lists that improve transcription of frequently used terms. Used with the `spoken_terms_id` parameter on the voice request session endpoint. |
| `tone` | target | `write` | Language supports tone selection (e.g. confident, diplomatic, enthusiastic). |
| `writing_style` | target | `write` | Language supports writing style selection (e.g. academic, casual, business). |

## Filtering by availability

By default, `GET /v3/languages` returns only stable languages and features. Use the `include` query parameter
to request additional languages and features based on their availability status:

| **Value** | **Effect** |
| - | - |
| `beta` | Includes languages and features in beta, in addition to stable |
| `external` | Includes features that rely on third-party service providers |

Values can be combined with repeated parameters: `?include=beta&include=external`.

The `status` field on each language object and each feature object indicates its availability:

| **Status** | **Meaning** |
| - | - |
| `stable` | Generally available |
| `beta` | Available for testing; may change |
| `early_access` | Limited availability; may change |

## Retrieving resources programmatically

Use the `/v3/languages/resources` endpoint to retrieve the list of resources and their features programmatically.
For each feature, the response indicates which languages must support it for the feature to be available —
source only, target only, or both — allowing clients to determine feature availability for a language pair
by checking the appropriate `features` objects.

```sh theme={null}
curl -X GET 'https://api.deepl.com/v3/languages/resources' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```

```json Example response (truncated) theme={null}
[
  {
    "name": "translate_text",
    "features": [
      {
        "name": "formality",
        "needs_target_support": true
      },
      {
        "name": "style_rules",
        "needs_target_support": true
      },
      {
        "name": "tag_handling",
        "needs_source_support": true,
        "needs_target_support": true
      },
      {
        "name": "glossary",
        "needs_source_support": true,
        "needs_target_support": true
      },
      {
        "name": "auto_detection",
        "needs_source_support": true
      }
    ]
  }
]
```

## Common use cases

The examples below show how to use the `/v3/languages` endpoints for common integration tasks. They are written
as pseudocode and are resource-agnostic unless otherwise noted.

### Populate source and target language dropdowns

A single call to `GET /v3/languages` returns all languages for a resource. Filter by `usable_as_source` and
`usable_as_target` to populate each dropdown separately.

```
GET /v3/languages?resource=translate_text

languages = response

source_options = languages.filter(l => l.usable_as_source)
target_options = languages.filter(l => l.usable_as_target)

render source_dropdown(source_options)
render target_dropdown(target_options)
```

### Show formality options only when supported

`formality` only needs to be supported by the target language. Check the selected target language's `features`
object — no need to look at the source language.

```
GET /v3/languages?resource=translate_text

languages = response
target = languages.find(l => l.lang == selected_target_lang)

if "formality" in target.features:
    show formality_selector  // e.g. ["default", "more", "less"]
else:
    hide formality_selector
```

### Check if a glossary can be used for a given language pair

`glossary` must be supported by both languages.

```
GET /v3/languages?resource=translate_text

languages = response

source = languages.find(l => l.lang == source_lang)
target = languages.find(l => l.lang == target_lang)

glossary_allowed = "glossary" in source.features
               and "glossary" in target.features
```

### List target languages that accept glossaries from a given source language

Filter to targets where both the source and target support the `glossary` feature.

```
GET /v3/languages?resource=translate_text

languages = response
source_lang = "en"

source = languages.find(l => l.lang == source_lang)

if "glossary" not in source.features:
    return []  // source doesn't support glossary at all

targets_with_glossary = languages
    .filter(l => l.usable_as_target)
    .filter(l => "glossary" in l.features)
```

### Show writing style options for the Write resource

`writing_style` is a target-only feature on the `write` resource. Check the target language's `features` object.

```
GET /v3/languages?resource=write

languages = response
target = languages.find(l => l.lang == selected_target_lang)

if "writing_style" in target.features:
    show writing_style_selector
else:
    hide writing_style_selector
```

### Check if style rules are available for a target language

Use `resource=style_rules` to query which languages support style rules. Style rules are target-language only — check
that the target language is listed in the response. The `style_rules` resource has no additional features, so only
the language availability needs to be checked.

```
GET /v3/languages?resource=style_rules

languages = response
target = languages.find(l => l.lang == selected_target_lang)

if target and target.usable_as_target:
    show style_rules_selector
else:
    hide style_rules_selector
```

### Determine feature support programmatically

Use `/v3/languages/resources` to drive feature checks at runtime — without hardcoding which features need
target-only or both-language support into your client.

```
GET /v3/languages/resources
GET /v3/languages?resource=translate_text

resources = first response
languages = second response

resource = resources.find(r => r.name == "translate_text")
source = languages.find(l => l.lang == source_lang)
target = languages.find(l => l.lang == target_lang)

for feature in resource.features:
    supported = true
    if feature.needs_source_support and feature.name not in source.features:
        supported = false
    if feature.needs_target_support and feature.name not in target.features:
        supported = false
```

## API stability

The v3 language endpoints are designed to be forward-compatible:

* New feature keys may be added to the `features` object
* New languages will be added as DeepL support expands
* Existing fields will not be removed or changed in backwards-incompatible ways

In rare cases, a language may be removed from the default response (for example, if it moves from stable
to beta). When this happens, it will still be accessible via `?include=beta`. We aim to avoid this, but
build your integration to handle languages disappearing from the response gracefully.

> [!NOTE]
>
> Build your integration to gracefully handle new BCP 47 `lang` codes and new feature keys in the `features` object. Do not hardcode assumptions about the format of language codes. See [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details.

## Best practices

1. **Cache responses**: Language support changes infrequently. Consider caching responses for up to 1 hour.

2. **Check features**: Always check the `features` object on language objects rather than assuming support (e.g. for formality, glossary use, or writing style).

3. **Handle forward compatibility**: New languages and features may be added at any time. Build your integration to dynamically accept new `lang` codes and new keys in the `features` object instead of maintaining a hardcoded allowlist.

4. **Use specific variants**: For target languages, prefer specific regional variants (e.g., `"en-US"`, `"en-GB"`) when the distinction matters to your users.


# API Usage Logger
Source: https://developers.deepl.com/docs/learning-how-tos/cookbook/api-usage-logger

Learn how to capture per-request DeepL API usage data and visualize it in a local dashboard.

> **[GitHub - DeepL/deepl-api-usage-logger](https://github.com/DeepL/deepl-api-usage-logger)**
>
> DeepL API Usage Logger on GitHub

This open-source reference project shows how to capture per-request usage data for the DeepL API (billed characters, language pairs, reporting tags, API key identifiers, and errors) and explore it through a local Streamlit dashboard. It wraps the [DeepL Python client](/docs/getting-started/client-libraries) so every text and document translation request is logged to a local DuckDB file as it happens, alongside any errors returned by the API.

The project is intended for teams that need usage reporting with request-level granularity. If you instead want to retrieve subscription-level or API key-level data via a single API call, see the [Usage Analytics Dashboard](/docs/learning-how-tos/cookbook/usage-analytics-dashboard) cookbook, which uses the [Admin API](/api-reference/admin-api/get-usage-analytics).

## Features

* **Per-request logging** for both text and document translation, with the source language, target language, billed characters, and a request ID stored for every call
* **Text translation requests with multiple texts** produce one row per text, all sharing the same `request_id`, so the language and character breakdown of each text within a multi-text request stays visible
* **Error capture alongside successes**, including the error code, HTTP status, and message, so reliability and usage live in the same dataset
* **Reporting tag and API key alias support**, letting you group usage by team, project, or service
* **Streamlit dashboard** with three views: a Usage summary table, an Error summary table, and a SQL Explorer for arbitrary DuckDB queries against the underlying table
* **CSV export** from every dashboard view
* **Non-blocking writes** that queue log entries on a background thread, so logging never adds latency to translation calls
* **Local stack** of Python, DuckDB, and Streamlit, with no external services required

## Screenshots

![Usage tab showing total billed characters, requests, and language pair breakdown](https://mintcdn.com/deepl-c950b784/kfy7-OvolE7AVebj/docs/learning-how-tos/cookbook/images/api-usage-logger-usage-tab.png?fit=max\&auto=format\&n=kfy7-OvolE7AVebj\&q=85\&s=371212024b2a270e5a3e95276923bd93)

![Errors tab showing failed requests grouped by error code and HTTP status](https://mintcdn.com/deepl-c950b784/kfy7-OvolE7AVebj/docs/learning-how-tos/cookbook/images/api-usage-logger-errors-tab.png?fit=max\&auto=format\&n=kfy7-OvolE7AVebj\&q=85\&s=08b47bf4e92def2a60a5aeb5f463bc53)

![SQL Explorer tab for running arbitrary DuckDB queries against the translation usage table](https://mintcdn.com/deepl-c950b784/kfy7-OvolE7AVebj/docs/learning-how-tos/cookbook/images/api-usage-logger-sql-explorer-tab.png?fit=max\&auto=format\&n=kfy7-OvolE7AVebj\&q=85\&s=971eaa327dc170f25da454eef7072713)


# Automating Indie Game Localization with the DeepL API and Godot
Source: https://developers.deepl.com/docs/learning-how-tos/cookbook/automating-indie-game-localization-with-the-deepl-api-and-godot

Efficiently translate content for a global audience and widen your game's reach

## Why Automate Game Localization?

As a game developer, reaching a global audience of people who speak other languages can significantly boost your game's visibility, player base, and overall success. Unfortunately, translating game content into multiple languages can easily be out of scope for solo devs, hobbyists, or indie studios. By combining the [open source Godot game engine](https://godotengine.org/) and the DeepL API, you can automate translations, localize your game's UI and dialogue, and easily reach a much wider audience.

In this blog post, we'll explore how to set up an automated translation system within Godot itself. This is a basic workflow example that you'll need to adapt for your own needs, use cases, and project setup, but we hope you can take some inspiration from it.

## Setting Up Your Translation Script

### Godot Script Overview

Our Godot 4.3 script leverages the DeepL API to translate predefined game text into multiple languages. It outputs these translations in a CSV format compatible with Godot, ready for use in your game.

Here's a breakdown of the script, which is written in Godot's built-in GDScript language. You can attach it to any kind of Godot node.

**1. Define Languages and Originals**

First, specify the languages you want to translate into and the original texts:

```gdscript theme={null}
var languages = [
    "DE", "ES", "JA" 
]

var originals = [
    {"key": "player_greeting", "original": "Hey there, ready for an adventure?", "context": "Player character; Initial interaction"},
    {"key": "exit", "original": "Press 'Exit' to leave.", "context": "Instruction; Button label for exiting the game"},
    {"key": "score", "original": "Your score is:", "context": "Result; Displayed after completing a level"},
]
```

**2. Initialize Translation Process**

When the script's node is ready, it initializes the translation process automatically. If you expand this script for your own needs you may want to attach this functionality to a button event so it doesn't run every time the script does.

```gdscript theme={null}
func _ready():
    on_translate()
```

These functions set up the translation structure for each language and loop through our list of desired target languages to send the requests to the DeepL API:

```gdscript theme={null}
func on_translate():
    for lang in languages:
        translations[lang] = {}
    start_translations()
    
func start_translations():
    for original in originals:
        request_translation(
            original["key"],
            original["original"],
            original["context"]
	)
```

**3. Request Translations**

For each original text, the script requests translations from the DeepL API. We're passing the additional `context`  for each string, as well as the  `prefer_less` formality option to maintain a lighthearted and casual tone for our game.

```gdscript theme={null}
func request_translation(key, original_text, context_text):
    for lang in languages:
        var http_request = HTTPRequest.new()
        add_child(http_request)
        http_request.connect("request_completed", _on_HTTPRequest_request_completed.bind(key, original_text, lang))
        
        var request_body = {
            "text": [original_text],
            "target_lang": lang,
            "context": context_text,
            "formality": "prefer_less"
        }
        var json = JSON.new()
        var json_content = json.stringify(request_body)
        var headers = ["Content-Type: application/json", "Authorization: DeepL-Auth-Key " + API_KEY]
        http_request.request(API_URL, headers, HTTPClient.METHOD_POST, json_content)
        translations_pending += 1
```

**4. Handle Translation Responses**

Once the API responds, the script processes the translations:

```gdscript theme={null}
func _on_HTTPRequest_request_completed(result, response_code, headers, body, key, original_text, target_lang):
    translations_pending -= 1
    print("Translation progress: ", originals.size() * languages.size() - translations_pending, "/", originals.size() * languages.size())
    
    if response_code == 200:
        var json = JSON.new()
        json.parse(body.get_string_from_utf8())
        var response = json.get_data()
        translations[target_lang][key] = response["translations"][0]["text"]
    else:
        print("HTTP request failed with response code: ", response_code)
    
    if translations_pending == 0:
        save_new_translations()
```

**5. Save Translations to CSV**

Finally, the script saves translations in a [CSV format that Godot can read natively](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_translations.html):

```gdscript theme={null}
func save_new_translations():
    var file_path = "res://translations/translations.csv"
    var file_content = "keys"
    
    for lang: String in languages:
        file_content += "," + lang.to_lower()
    file_content += "\n"
    
    for original in originals:
        file_content += original["key"]
        for lang in languages:
            var translation = translations[lang][original["key"]]
            file_content += ",\"" + translation.replace("\"", "\"\"") + "\""
        file_content += "\n"
    
    save_to_file(file_path, file_content)
    print("Translations saved to: " + file_path)
```

This will produce a `.csv` file with the following content:

```csv theme={null}
keys,de,es,ja
player_greeting,"Hallo, bist du bereit für ein Abenteuer?","Hola, ¿preparado para una aventura?","やあ、冒険の準備はいいかい？"
exit,"Drücke ""Beenden"", um das Spiel zu verlassen.","Pulsa ""Salir"" para salir.","'Exit'を押して退出してください。"
score,"Dein Ergebnis ist:","Tu puntuación es:","あなたのスコアは:"
```

### Wrapping Up

As you expand your game, consider developing a more sophisticated system to handle larger amounts of content. You could implement batch processing, caching of existing translations, a Godot-based UI for entering and editing original content, advanced error handling, and dynamic language selection.

This is just a quick example of how you can incorporate the DeepL API into a game project to enable effortless translation of your game's dialogue and other text content, allowing even solo developers access to an efficient and scaleable localization process that will enable their projects to reach players all over the world.


# Project: Google Sheets
Source: https://developers.deepl.com/docs/learning-how-tos/cookbook/google-sheets

Open-source example showing how to build a Google Sheets App using the DeepL API.

This sample explains in detail how an App for Google Sheets can be built to integrate DeepL translations into Google Sheets. This also works quite similarly for Google Docs!

> **[GitHub - DeepL/google-sheets-example: Example using DeepL API in Google Sheets scripts](https://github.com/DeepL/google-sheets-example)**
>
> Google Sheet Example on Github


# Building a Document Translator with the DeepL API
Source: https://developers.deepl.com/docs/learning-how-tos/cookbook/java-document-translator

Streamline document localization workflows with automated translation for businesses and developers

## Why Build a Document Translator?

In today's global business environment, organizations frequently need to translate various document types - from technical manuals and legal contracts to marketing materials and internal communications. Manually uploading files to web-based translation services can be time-consuming and inefficient, especially when dealing with multiple documents.

By building a command-line Java application with the DeepL API, you can automate document translation processes, integrate them into CI/CD pipelines, and provide a reliable solution for bulk document processing. This approach is particularly valuable for:

* **Development teams** who need to localize documentation and user manuals
* **Content teams** managing multilingual marketing materials
* **Businesses** requiring regular translation of contracts, reports, and communications
* **Automation workflows** where translation needs to be triggered programmatically

## Setting Up Your Document Translator

### Prerequisites

Before you begin, you'll need:

* Java Development Kit (JDK) 8 or higher
* Apache Maven for dependency management
* A DeepL API key (get one at [DeepL API](https://www.deepl.com/pro-api))
* Basic familiarity with Java and command-line tools

### Project Overview

Our Java application leverages the official DeepL Java SDK to translate documents across multiple formats. It provides a simple command-line interface that takes an input file and target language, automatically generating appropriately named output files.

Here's the complete implementation breakdown:

#### 1. Project Setup and Dependencies

First, let's set up the Maven project structure with the necessary dependencies:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>java-document-translator</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.deepl.api</groupId>
            <artifactId>deepl-java</artifactId>
            <version>1.10.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.0.0</version>
                <configuration>
                    <mainClass>App</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
```

The `deepl-java` dependency provides all the necessary functionality for interacting with the DeepL API, including document translation capabilities.

#### 2. Supported File Types Definition

We start by defining the supported file formats to provide clear feedback to users:

```java theme={null}
private static final Map<String, String> SUPPORTED_EXTENSIONS;

static {
    Map<String, String> map = new HashMap<>();
    map.put("docx", "Microsoft Word Document");
    map.put("doc", "Microsoft Word Document");
    map.put("pptx", "Microsoft PowerPoint Document");
    map.put("xlsx", "Microsoft Excel Document");
    map.put("pdf", "Portable Document Format");
    map.put("htm", "HTML Document");
    map.put("html", "HTML Document");
    map.put("txt", "Plain Text Document");
    map.put("xlf", "XLIFF Document (1.2 / 2.0 / 2.1)");
    map.put("xliff", "XLIFF Document (1.2 / 2.0 / 2.1)");
    map.put("srt", "SubRip Subtitle file");
    map.put("idml", "Adobe InDesign Markup Language");
    map.put("xml", "XML Document");
    map.put("json", "JSON Document");
    map.put("dita", "DITA topic");
    map.put("mif", "Adobe FrameMaker Interchange Format");
    SUPPORTED_EXTENSIONS = Collections.unmodifiableMap(map);
}
```

This static initialization ensures our application can quickly validate file types before attempting translation, providing immediate feedback for unsupported formats.

#### 3. Command Line Argument Processing

The application expects two command-line arguments: the input file path and target language code. The source language is automatically detected by the DeepL API.

```java theme={null}
public static void main(String[] args) {
    String inputFilePath = args[0];
    String targetLang = args[1];
    
    // Validate file extension
    String extension = "";
    int i = inputFilePath.lastIndexOf('.');
    if (i > 0 && i < inputFilePath.length() - 1) {
        extension = inputFilePath.substring(i + 1);
        String lowerCaseExtension = extension.toLowerCase();
        if (SUPPORTED_EXTENSIONS.containsKey(lowerCaseExtension)) {
            System.out.println("File type: " + SUPPORTED_EXTENSIONS.get(lowerCaseExtension));
        } else {
            System.err.println("Error: Unsupported file extension '" + extension + "'");
            return;
        }
    }
}
```

#### 4. Output File Path Generation

One key feature is automatic output file naming, which prevents accidental overwrites and clearly identifies translated versions:

```java theme={null}
// Auto-generate output file path
Path inputPathObject = Paths.get(inputFilePath);
String originalFileName = inputPathObject.getFileName().toString();
String newFileName = targetLang.toUpperCase() + "_" + originalFileName;
Path outputFilePathObject = inputPathObject.resolveSibling(newFileName);
String outputFilePath = outputFilePathObject.toString();
```

This approach transforms `document.pdf` with target language `DE` into `DE_document.pdf`, making it easy to identify translated versions.

#### 5. DeepL API Integration

The core translation functionality uses the DeepL Java SDK:

```java theme={null}
// Initialize DeepL client
String authKey = System.getenv("DEEPL_AUTH_KEY");
if (authKey == null || authKey.isEmpty()) {
    System.err.println("Error: DEEPL_AUTH_KEY environment variable not set.");
    return;
}

File inputFile = Paths.get(inputFilePath).toFile();
File outputFile = Paths.get(outputFilePath).toFile();
DeepLClient client = new DeepLClient(authKey);

// Perform translation
DocumentStatus status = client.translateDocument(inputFile, outputFile, null, targetLang);
System.out.println("Document translation initiated. Document ID: " + status.getDocumentId());
```

#### 6. Translation Status Monitoring

Document translation is asynchronous, so we need to monitor the process:

```java theme={null}
System.out.println("Waiting for translation to complete...");

while (true) {
    StatusCode statusCode = status.getStatus();
    if (statusCode == StatusCode.Done) {
        System.out.println("Translation completed successfully.");
        break;
    }
    if (statusCode == StatusCode.Error) {
        System.err.println("Error during translation: " + status.getErrorMessage());
        break;
    }
    
    Thread.sleep(1000); // Wait 1 second before checking status again
}
```

This polling mechanism ensures the application waits for translation completion and provides appropriate feedback.

### Building and Running

1. **Set up your environment:**

```bash theme={null}
export DEEPL_AUTH_KEY="your_deepl_api_key_here"
```

2. **Build the project:**

```bash theme={null}
mvn compile
```

3. **Run translations:**

Here are some practical examples of using the translator:

**Translating Technical Documentation:**

```bash theme={null}
mvn exec:java -Dexec.args="./api-documentation.pdf EN-US"
```

**Localizing Marketing Materials:**

```bash theme={null}
mvn exec:java -Dexec.args="./brochure.docx JA"
```

**Processing Subtitle Files:**

```bash theme={null}
mvn exec:java -Dexec.args="./movie-subtitles.srt DE"
```

### Wrapping Up

This Java document translator provides a solid foundation for automating document localization workflows. By combining the reliability of Java with DeepL's translation quality, you can build scalable solutions for various business needs.

The command-line interface makes it easy to integrate into existing automation scripts, CI/CD pipelines, or batch processing workflows. Whether you're a developer localizing documentation or a business automating multilingual content creation, this approach offers a practical solution for programmatic document translation.

The extensible design allows for easy customization and enhancement, making it adaptable to specific organizational requirements while maintaining the core functionality of reliable, high-quality document translation.

## References

* [DeepL API Documentation](https://developers.deepl.com/docs)
* [DeepL Java SDK](https://github.com/DeepL/deepl-java)
* [Maven Exec Plugin](https://www.mojohaus.org/exec-maven-plugin/)
* [DeepL Supported Languages](https://www.deepl.com/docs-api/translate-text/target-language/)


# Making API calls from client-side JavaScript
Source: https://developers.deepl.com/docs/learning-how-tos/cookbook/nodejs-proxy

Two lightweight local proxies that let you try the DeepL API directly from a website

> [!NOTE]
>
> These proxies are intended for prototyping and frontend testing. For production environments, consider implementing your own backend service with additional security measures and rate limiting.

## Rationale

The DeepL API does not permit calls from client-side JavaScript - that is, from JavaScript running in a browser. This policy exists to keep your API key safe. When you place a call from your website directly to the DeepL API, that call needs to include your API key. Anyone using your website could look at the network calls or your code itself, find your API key, and use it themselves.

For this and other security considerations, DeepL [does not enable the CORS headers](/docs/best-practices/cors-requests) you would need to call the API from a webpage hosted on your origin. The industry-standard approach is to call APIs like DeepL’s from a back-end service. DeepL enforces this best practice to keep your credentials secure.

## When to use a quick proxy

But what do you do if you want to use the API quickly, in a prototype, a demo, or a hackathon, where you need to get up and running fast? What if you don’t have easy access to a server?

For such situations, here are two solutions.

## Node.js Proxy Server

> **[GitHub - DeepL/deepl-api-nodejs-proxy](https://github.com/DeepL/deepl-api-nodejs-proxy)**
>
> DeepL API Node.js Proxy on GitHub

This full-featured proxy server supports all DeepL API endpoints, including text translation, document translation, and glossaries. Built with Node.js and Express with minimal dependencies, it handles CORS headers for you and keeps your API key secure. It even includes an interactive web demo for testing translations right in your browser.

This proxy includes an interactive setup wizard to get you started quickly. Clone the repo, run the setup, and start sending requests from your browser. Check out the [GitHub repository](https://github.com/DeepL/deepl-api-nodejs-proxy) for full setup instructions and Docker support.

## Quick & dirty PHP proxy

If you’re just using our `/translate` endpoint and want an even quicker solution, or if you don’t use node.js, you could use the PHP code below to create an instant proxy server. If PHP is not already installed on your machine, you can download and install it at [php.net](https://www.php.net/downloads.php).

The PHP script takes the parameters in the query string and passes them into a `POST` request to `/translate`. It does not check that the parameters are valid and does not support any other endpoints, although you could modify it to do so.

To use this while developing on your local machine:

* replace `{your API key here}` with your actual API key
* create a file in your favorite directory with the PHP code below
* go to your terminal and visit that directory
* type `php -S localhost:8000`

Your JavaScript can then access the DeepL API at `http://localhost:8000/php-proxy.php`. For example, to send a translation request with `text` and `target_lang`:

```javascript theme={null}
const url = `http://localhost:8000/deepl-proxy.php?text=${encodeURIComponent(text)}&target_lang=${encodeURIComponent(targetLang)}`;
const response = await fetch(url);
const result = await response.text();
```

Here is the PHP script:

```php theme={null}
<?php
header('Content-Type: application/json');
header('Access-Control-Allow-Origin: *');

$apiKey = '{your API key here}';
$apiUrl = 'https://api.deepl.com/v2/translate';

$data = http_build_query($_GET);

$context = stream_context_create([
  'http' => [
      'method' => 'POST',
      'header' => "Authorization: DeepL-Auth-Key " . $apiKey . "\r\n" .
                  "Content-Type: application/x-www-form-urlencoded\r\n",
      'content' => $data
  ]
]);

echo file_get_contents($apiUrl, false, $context);
?>
```

## Screenshots

### Node.js proxy

![Node.js proxy server running and ready to accept requests](https://raw.githubusercontent.com/DeepL/deepl-api-nodejs-proxy/main/assets/proxy-running.png)

Node.js proxy server running in a terminal

![Interactive web demo interface for testing translations](https://raw.githubusercontent.com/DeepL/deepl-api-nodejs-proxy/main/assets/dashboard-demo.png)

Interactive web demo interface for testing translations

### PHP proxy

![](https://mintcdn.com/deepl-c950b784/Y95QuvGCKwvFbDIC/_assets/images/php-proxy-screenshot.png?fit=max\&auto=format\&n=Y95QuvGCKwvFbDIC\&q=85\&s=85e51655adcf7aebacaa939b625f9aa7)

PHP proxy running in a terminal


# Sending Custom Reporting Tags with Client Libraries
Source: https://developers.deepl.com/docs/learning-how-tos/cookbook/sending-custom-reporting-tags-from-client-libraries

Code snippets for attaching X-DeepL-Reporting-Tag to translate requests using the official DeepL client libraries.

This recipe shows how to attach a custom reporting tag to translate requests using each official DeepL client library. For an overview of what custom reporting tags are, how they're stored, and how to query their usage, see [How to Use Custom Reporting Tags](/docs/learning-how-tos/examples-and-guides/how-to-use-custom-reporting-tags).

## Recommended pattern: one client per tag

The Python, Node.js, Java, .NET, and PHP client libraries let you attach custom HTTP headers when constructing a `DeepLClient`. The simplest way to tag your requests is to construct one `DeepLClient` per tag value, configure it with `X-DeepL-Reporting-Tag` once, and reuse it for every request that should carry that tag.

Each `DeepLClient` instance owns its own HTTP connection pool, so keep instances around and reuse them rather than constructing a new client per request.

The Ruby library (`deepl-rb`, v3.8.0 and later) uses a module-level API and accepts an `additional_headers` argument on each `translate` call instead of a client-level option. Pass `X-DeepL-Reporting-Tag` on every call you want to tag.

## Code snippets

The snippets below all send the same translate request (`"Welcome to your dashboard." → DE`) and tag it as `team-billing`. Replace `YOUR_AUTH_KEY` with your DeepL API authentication key.

**Python**

```python theme={null}
import deepl

client = deepl.DeepLClient("YOUR_AUTH_KEY")
client.headers["X-DeepL-Reporting-Tag"] = "team-billing"

result = client.translate_text(
    "Welcome to your dashboard.",
    target_lang="DE",
)
print(result.text)
```

The Python library exposes `client.headers` as a public dictionary. Setting the key after construction merges with the library-managed `Authorization` and `User-Agent` headers.

**Node.js**

```typescript theme={null}
import * as deepl from 'deepl-node';

const client = new deepl.DeepLClient('YOUR_AUTH_KEY', {
  headers: { 'X-DeepL-Reporting-Tag': 'team-billing' },
});

const result = await client.translateText(
  'Welcome to your dashboard.',
  null,
  'DE',
);
console.log(result.text);
```

The `headers` option on `DeepLClientOptions` is merged with the library-managed `Authorization` and `User-Agent` headers at construction time.

**Java**

```java theme={null}
import com.deepl.api.*;
import java.util.Map;

DeepLClientOptions options = new DeepLClientOptions()
    .setHeaders(Map.of("X-DeepL-Reporting-Tag", "team-billing"));

DeepLClient client = new DeepLClient("YOUR_AUTH_KEY", options);

TextResult result = client.translateText(
    "Welcome to your dashboard.",
    null,
    "DE"
);
System.out.println(result.getText());
```

`DeepLClientOptions.setHeaders` accepts any `Map<String, String>`. The configured headers are sent on every request issued by this client.

**.NET**

```csharp theme={null}
using DeepL;

var options = new DeepLClientOptions {
    Headers = new Dictionary<string, string?> {
        { "X-DeepL-Reporting-Tag", "team-billing" }
    }
};

var client = new DeepLClient("YOUR_AUTH_KEY", options);

var result = await client.TranslateTextAsync(
    "Welcome to your dashboard.",
    null,
    "DE"
);
Console.WriteLine(result.Text);
```

`DeepLClientOptions.Headers` is a `Dictionary<string, string?>`. Headers configured here are attached to every request the client makes.

**PHP**

```php theme={null}
<?php
require __DIR__ . '/vendor/autoload.php';

$client = new \DeepL\DeepLClient('YOUR_AUTH_KEY', [
    'headers' => [
        'X-DeepL-Reporting-Tag' => 'team-billing',
    ],
]);

$result = $client->translateText(
    'Welcome to your dashboard.',
    null,
    'DE'
);
echo $result->text;
```

The `headers` option in the constructor's options array is merged with the library-managed `Authorization` and `User-Agent` headers.

**Ruby**

```ruby theme={null}
require 'deepl'

DeepL.configure do |config|
  config.auth_key = 'YOUR_AUTH_KEY'
end

additional_headers = { 'X-DeepL-Reporting-Tag' => 'team-billing' }

result = DeepL.translate(
  'Welcome to your dashboard.',
  'EN',
  'DE',
  {},
  additional_headers
)
puts result.text
```

`additional_headers` is the fifth positional argument on `DeepL.translate`. Pass an empty options hash (`{}`) before it when you don't need any other translate options. The headers are merged with the library-managed `Authorization` and `User-Agent` headers on each request. Requires `deepl-rb` v3.8.0 or later.

**Output (all snippets):**

```
Willkommen in Ihrem Dashboard.
```

> [!TIP]
>
> To confirm `X-DeepL-Reporting-Tag` is leaving your client correctly, point the SDK at [deepl-mock](https://github.com/DeepL/deepl-mock) via the `server_url` / `serverUrl` option and inspect the headers it logs. Useful for catching configuration mistakes before sending real tagged traffic.

## Tagging across many values

The one-client-per-tag pattern works well when your tag dimension is bounded: teams, products, or a handful of business units. If you need to tag with high-cardinality values, such as a unique tag per end customer, holding a `DeepLClient` instance for every value isn't practical.

Today, none of the client libraries expose per-request custom headers through their public translate methods. The HTTP client layers in deepl-node, deepl-python, and deepl-php already support per-request header injection internally, so the foundation is in place. The Java and .NET libraries support only per-instance headers.

Updates to extend per-request custom-header support across the client libraries are planned. Until those updates land, the per-instance pattern above is the supported path.

## Next steps

* **Concepts and limits:** Read [How to Use Custom Reporting Tags](/docs/learning-how-tos/examples-and-guides/how-to-use-custom-reporting-tags) for the validation rules, naming guidance, and the relationship between tags and API keys.
* **Query tagged usage:** See the [Get custom tag usage analytics](/api-reference/admin-api/get-custom-tag-usage-analytics) reference.


# Usage Analytics Dashboard
Source: https://developers.deepl.com/docs/learning-how-tos/cookbook/usage-analytics-dashboard

A demo dashboard for visualizing DeepL API key usage across an entire account using the Admin API.

> **[GitHub - DeepL/usage-analytics-demo-dashboard](https://github.com/DeepL/usage-analytics-demo-dashboard)**
>
> Usage Analytics Demo Dashboard on GitHub

This open-source demo dashboard shows how to visualize DeepL API key usage across your entire account, powered by a single API call to the `/v2/admin/analytics` endpoint. It provides interactive charts, flexible date ranges, and per-API-key breakdowns to help you monitor and analyze your API usage.

The dashboard is designed to be lightweight and easy to set up, with zero NPM dependencies and sample data included for testing. It can be used as-is, or as an example of how similar data can be incorporated into your own internal workflows and dashboards.

For more information about the DeepL Admin API endpoint, check out the [Admin API documentation](/api-reference/admin-api/get-usage-analytics).

If you need per-request logging instead of account-wide views, see the [API Usage Logger](/docs/learning-how-tos/cookbook/api-usage-logger) cookbook.

## Features

* **Interactive charts and visualizations** - View your usage data through multiple chart types
* **Flexible date ranges** - Analyze usage over rolling periods or fixed date ranges
* **Per-API-key breakdown** - See usage broken down by individual API keys
* **Basic trends and forecasting** - Identify patterns in your API usage
* **Secure local configuration** - All configuration stays on your machine
* **Zero NPM dependencies** - Chart.js loaded from CDN for simplicity
* **Sample data included** - Test and demo without connecting to your account

## Screenshots

![Dashboard Overview showing character usage and usage by feature type](https://mintcdn.com/deepl-c950b784/T1_WIv7Qt4aU2i7E/docs/learning-how-tos/cookbook/images/dashboard-overview.png?fit=max\&auto=format\&n=T1_WIv7Qt4aU2i7E\&q=85\&s=610cba4450684754bf54f44811ce7937)

![Usage by API Key comparison chart showing top 5 keys](https://mintcdn.com/deepl-c950b784/T1_WIv7Qt4aU2i7E/docs/learning-how-tos/cookbook/images/usage-by-api-key.png?fit=max\&auto=format\&n=T1_WIv7Qt4aU2i7E\&q=85\&s=79dc856cd1a2271d47adc2488b7661c0)

![Daily usage trends across all API keys](https://mintcdn.com/deepl-c950b784/T1_WIv7Qt4aU2i7E/docs/learning-how-tos/cookbook/images/usage-trends.png?fit=max\&auto=format\&n=T1_WIv7Qt4aU2i7E\&q=85\&s=8c909ba34f53185d9144259dceee587e)


# How to Use the Context Parameter Effectively
Source: https://developers.deepl.com/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter

Learn when and how to use the context parameter to improve translation accuracy for ambiguous content.

**This guide shows you:**

* When to use `context` (and when not to)
* How to use `context` to resolve ambiguous words, genders, or transliterations
* Where to find a comparison of `context` with DeepL's customization features

***

## What the context parameter is for

The `context` parameter helps DeepL's API translate ambiguous words and short text snippets more accurately by providing the surrounding content. Think of it like showing a human translator the paragraphs before and after the sentence being translated.

The `context` parameter can help with:

* Picking the correct translation for ambiguous words
* Providing grammatical clues for gender, number, or case that isn't clear from the text alone
* Improving translations of short snippets such as headlines or product names

## What the context parameter is NOT for

> [!WARNING]
>
> **Common Misconception:** Many users try to use `context` like ChatGPT system prompts. **This does not work reliably.**

The `context` parameter is **not** designed for:

* LLM-style instructions: "Translate with a friendly, casual tone"
* Translation rules: "Always translate 'Tor' as 'gate'"
* Cultural context: "Adapt for German cultural norms"

Using `context` like this will produce unpredictable results. The parameter is optimized for document content, not commands.

Instead, try:

* [Style rules and custom instructions](/docs/customize/using-style-rules): For tone, style, formatting, and translation instructions
* [Glossaries](/docs/customize/managing-glossaries): For consistent terminology and brand names

***

## How to use context for ambiguous words

When a word has multiple meanings, surrounding context helps the translation engine choose the correct interpretation.

### Example

"Tor" could mean "gate" or "goal" in German. Without context, DeepL may not know which meaning you intend:

```sh theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [your key]' \
--header 'Content-Type: application/json' \
--data '{
  "text": [
    "Die Person stand vor dem Tor."
  ],
  "target_lang": "EN-US"
}'
```

**Output without context:**

```text theme={null}
"The person was standing in front of the gate."
```

If you're writing about a football game, provide context to clarify:

```sh theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [your key]' \
--header 'Content-Type: application/json' \
--data '{
  "text": [
    "Die Person stand vor dem Tor."
  ],
  "target_lang": "EN-US",
  "context": "Es war ein Fußballspiel."
}'
```

**Output with context:**

```text theme={null}
"The person was standing in front of the goal."
```

### When to use this approach

* You're translating short snippets that lack built-in context
* The text contains words with multiple meanings
* The surrounding content makes the intended meaning clear

***

## How to use context for grammatical gender

When grammatical gender isn't clear from the source text, context can provide the necessary clues.

### Example

Without context, DeepL may not use the desired gender when translating:

```sh theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [your key]' \
--header 'Content-Type: application/json' \
--data '{
  "text": [
    "The teacher asked the class to tidy up after they finished the lesson."
  ],
  "target_lang": "DE"
}'
```

**Output without context:** (uses masculine form "Lehrer")

```text theme={null}
"Der Lehrer bat die Klasse, nach der Stunde aufzuräumen."
```

You can provide context from the surrounding text that clarifies the teacher's gender:

```sh theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [your key]' \
--header 'Content-Type: application/json' \
--data '{
  "text": [
    "The teacher asked the class to tidy up after they finished the lesson."
  ],
  "target_lang": "DE",
  "context": "She did not want to tidy up herself."
}'
```

**Output with context:** (uses feminine form "Lehrerin")

```text theme={null}
"Die Lehrerin bat die Klasse, nach der Stunde aufzuräumen."
```

### When to use this approach

* Translating into languages with grammatical gender
* The source text doesn't specify gender
* You have surrounding sentences that contain gender clues

***

## How to use context for consistent name translation

When translating names in headlines or short snippets, the same name might be transliterated differently unless additional context is provided.

### Example

As noted in the [`text` field reference](/api-reference/translate/request-translation), each text in the array is translated independently and texts do not share context with each other. This results in different transliterations for the name "Sergej".

```sh theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [your key]' \
--header 'Content-Type: application/json' \
--data '{
  "text": [
    "Sergej gibt Stellungnahme ab",
    "Sergej Zhivkov erklärte gestern, dass neue Maßnahmen ergriffen werden."
  ],
  "source_lang": "DE",
  "target_lang": "EN-US"
}'
```

**Output without context:**

```json theme={null}
{
  "translations": [
    {
      "detected_source_language": "DE",
      "text": "Sergej makes a statement"
    },
    {
      "detected_source_language": "DE",
      "text": "Sergei Zhivkov explained yesterday that new measures will be taken."
    }
  ]
}
```

Providing a longer snippet of `context` containing the complete name results in consistent transliteration:

```sh theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [your key]' \
--header 'Content-Type: application/json' \
--data '{
  "text": [
    "Sergej gibt Stellungnahme ab",
    "Sergej Zhivkov erklärte gestern, dass neue Maßnahmen ergriffen werden."
  ],
  "source_lang": "DE",
  "target_lang": "EN-US",
  "context": "Sergej Zhivkov erklärte gestern, dass neue Maßnahmen ergriffen werden."
}'
```

**Output with context:**

```json theme={null}
{
    "translations": [
        {
            "detected_source_language": "DE",
            "text": "Sergei issues statement"
        },
        {
            "detected_source_language": "DE",
            "text": "Sergei Zhivkov declared yesterday that new measures will be taken."
        }
    ]
}
```

### When to use this approach

* Translating news headlines separately from article bodies
* Transliterating names with multiple possible spellings in your target language

***

## Choosing the right feature

The `context` parameter is one of several ways to influence translation output. For a comparison of `context` with glossaries, style rules, custom instructions, and translation memories, see [Choosing the right feature](/docs/customize/overview#choosing-the-right-feature).

***

## Technical details

### Cost

Characters in the `context` parameter do not count toward billing. Only characters sent in the `text` parameter are billed.

### Size limit

There is no size limit for the `context` parameter itself, but the request body size limit of 128 KiB applies to all text translation requests.

### Multi-`text` requests

As noted in the [`text` field reference](/api-reference/translate/request-translation), each text in the array is translated independently — they do not share context with each other.

In this example, "Tor" might be translated as "gate" instead of "goal" because the first `text` doesn't have access to the second one's content.

```python theme={null}
{
  "text": [
    "Die Person stand vor dem Tor.",
    "Es war ein Fußballspiel."
  ],
  "target_lang": "EN-US"
}
```

To ensure "Tor" is translated as "goal", you can add additional sentences into the `context` parameter, or keep related content together in one `text` parameter.

If you send a request with both `context` and multiple `text` parameters, the `context` parameter will be applied to each one.

### Document translation

When using the [document translation endpoint](/api-reference/document/upload-and-translate-a-document), the engine automatically uses the broader document context. You don't need to provide explicit context for full documents.

### Tag handling

When using `tag_handling=xml` or `tag_handling=html`, tags are *not* used as a context boundary. The translation engine automatically looks across all content provided in each `text` parameter. As with other types of texts, you may need to provide additional `context` when translating single tags without surrounding content.

***

## Next steps

Now that you understand the context parameter:

* **Try it yourself:** Review the [text translation API reference](/api-reference/translate/request-translation) for complete context parameter specifications
* **Enforce terminology:** Learn how to use [glossaries](/docs/customize/managing-glossaries) for consistent translations across all content
* **Control style and tone:** Explore [style rules](/docs/customize/using-style-rules) for formatting and tone instructions
* **Translate full documents:** Understand how [document translation](/api-reference/document/upload-and-translate-a-document) automatically handles context


# How to Use Custom Reporting Tags
Source: https://developers.deepl.com/docs/learning-how-tos/examples-and-guides/how-to-use-custom-reporting-tags

Learn how to attach reporting tags to text translation and Voice API requests so you can break down usage by team, project, or category.

**This guide shows you:**

* When to use custom reporting tags
* How to attach a tag to a text translation or Voice API request via the `X-DeepL-Reporting-Tag` header
* Tag naming guidance and current limitations

***

## What custom reporting tags are for

Custom reporting tags let your organization attribute API usage to a team, project, customer, or any other category you care about. You attach a tag to each request, and you can then retrieve usage broken down by those tags in two ways: programmatically via the [Get custom tag usage analytics](/api-reference/admin-api/get-custom-tag-usage-analytics) endpoint, or as a [custom tag-level CSV export](/docs/admin/retrieving-usage-data#csv-export) from the account UI.

Common use cases:

* **Multi-tenant applications**: attribute translation volume to the end customer making each request
* **Internal cost allocation**: split usage across teams or business units that share a single API key

Only tagged requests appear in custom-tag reports, so tag every request you want to track.

> [!WARNING]
>
> Custom tag data is recorded only for text translation and Voice API requests. Support for additional request types will be added in a future update.

***

## How to tag a translate request

Set the optional `X-DeepL-Reporting-Tag` header on your translate request. You define the tag value; no registration is required before sending it. See [Tag naming guidance](#tag-naming-guidance) and [Limitations](#limitations) for the rules tag values must follow.

```sh theme={null}
curl --request POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [your key]' \
--header 'X-DeepL-Reporting-Tag: team-billing' \
--header 'Content-Type: application/json' \
--data '{
  "text": ["Welcome to your dashboard."],
  "target_lang": "DE"
}'
```

**Sample response:**

```json theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Willkommen in Ihrem Dashboard."
    }
  ]
}
```

The translate response is unchanged by tagging. The tag is recorded server-side and surfaces only in custom-tag usage reports: the analytics endpoint and the CSV export.

***

## How to tag a Voice API session

Set the same header on the [session request](/api-reference/voice/request-session). The tag applies to the whole session, so all audio streamed over the resulting WebSocket connection is attributed to it.

```sh theme={null}
curl --request POST 'https://api.deepl.com/v3/voice/realtime' \
--header 'Authorization: DeepL-Auth-Key [your key]' \
--header 'X-DeepL-Reporting-Tag: team-billing' \
--header 'Content-Type: application/json' \
--data '{
  "source_media_content_type": "audio/ogg;codecs=opus",
  "source_language_mode": "auto",
  "target_languages": ["de"]
}'
```

**Sample response:**

```json theme={null}
{
  "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect",
  "token": "VGhpcyBpcyBhIGZha2UgdG9rZW4K",
  "session_id": "4f911080-cfe2-41d4-8269-0e6ec15a0354"
}
```

The WebSocket connection itself carries no headers, so the session request is the only place a tag can be set. You cannot change or add a tag once a session is running, and you cannot tag individual audio chunks within a session. To attribute audio to more than one tag, open a separate session per tag.

The tag survives [reconnection](/api-reference/voice/reconnect-session): audio streamed after you exchange a token for a new streaming URL is still attributed to the tag set on the original session request, and you do not resend the header.

***

## Tag naming guidance

A few practices keep your reports clean:

* Tags are caller-defined strings. The API records the value you send after applying the normalization rules below.
* Before storage, the API trims leading and trailing whitespace and lowercases the value, so `"  Sample-Tag"` is recorded as `sample-tag` and appears that way in analytics responses.
* After normalization, characters are matched exactly. `team-billing` and `team_billing` report as two separate tags.
* Pick a convention and stick to it. Examples: `team-billing`, `customer-{id}`, `project-{id}`.

***

## Tags and API keys

A custom tag is independent of the API key that sent the request. The same tag value can be used across multiple API keys in your organization, and usage from every key that sends `team-billing` rolls up to a single `team-billing` row in the analytics response.

The custom-tag analytics endpoint groups by tag only. Combined breakdowns such as tag-by-API-key or API-key-by-tag are not supported. For a per-key view of usage, use the [Get usage analytics](/api-reference/admin-api/get-usage-analytics) endpoint instead.

Tags are a reporting feature only. You cannot use them to enforce limits, quotas, or any per-request controls. If you need separate controls across workloads, such as capping staging consumption or disabling translation for a specific environment, use a separate API key for each workload and configure [cost control limits](/docs/best-practices/cost-control) per key.

***

## Limitations

* Tag values are limited to 100 characters. Requests with longer values are rejected with a 400 response.
* Tag values must use ASCII characters only, with no internal whitespace and no control characters. Values like `sample tag`, `sample-tág`, or `sample\ntag` are rejected with a 400 response. Leading and trailing whitespace is trimmed before validation (see [Tag naming guidance](#tag-naming-guidance)).
* Each request accepts one tag. Sending multiple values in the header is not supported.
* For the Voice API, a tag covers a whole session and can only be set on the session request. See [How to tag a Voice API session](#how-to-tag-a-voice-api-session).
* Untagged requests are not included in custom-tag analytics. They still count toward your overall usage, which you can retrieve through the [Get usage analytics](/api-reference/admin-api/get-usage-analytics) endpoint.

***

## Next steps

* **Use the client libraries:** See [Sending Custom Reporting Tags with Client Libraries](/docs/learning-how-tos/cookbook/sending-custom-reporting-tags-from-client-libraries) for code snippets in Python, Node.js, Java, .NET, and PHP.
* **Query your tagged usage:** See the [Get custom tag usage analytics](/api-reference/admin-api/get-custom-tag-usage-analytics) reference for date ranges, aggregation options, and pagination, or download a [custom tag-level CSV export](/docs/admin/retrieving-usage-data#csv-export) from the account UI.
* **Get the bigger picture:** Read the [usage data guide](/docs/admin/retrieving-usage-data) to understand how custom-tag reporting fits alongside the other usage data sources.
* **Explore other optional translate parameters:** Learn [how to use the context parameter](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter) to improve translation accuracy for ambiguous content.


# Mustache placeholder tags
Source: https://developers.deepl.com/docs/learning-how-tos/examples-and-guides/placeholder-tags

An example for working with placeholder tags—in this case, Mustache tags.

Mustache is a template system that provides “logic-less templates”. [From the Mustache manual](https://mustache.github.io/mustache.5.html):

*Mustache can be used for HTML, config files, source code - anything. It works by expanding tags in a template using values provided in a hash or object.*

Using the DeepL API to translate text that includes Mustache tags can present a challenge. In most if not all cases, users would *not* want to translate the tag key inside a Mustache tag, as the tag key is used to reference values in a hash or object. However, the DeepL API does not recognize Mustache tags and does not have a built-in parameter that can be used to exclude them from translation.

It is possible, however, to pre- and post-process text containing Mustache tags in order to preserve the Mustache tag key during translation. In the Python client library, [we include an example](https://github.com/DeepL/deepl-python/tree/main/examples/mustache) showing how this can be done.

A similar approach could be used for other types of placeholder tags that are not recognized by the DeepL API when users do not want to translate the content inside the tags.

Below is a summary of the Mustache example, and for more detail, you can refer to the [example's README](https://github.com/DeepL/deepl-python/blob/main/examples/mustache/README.md).

* The input Mustache template is parsed to separate the literal text from the Mustache tags.
* The template is modified to replace all Mustache tags with placeholder XML tags. Unique IDs are attached to each placeholder tag to identify them in the translated XML.
* The XML template is translated using DeepL API with XML tag handling activated.
* The translated XML is parsed to identify placeholder tags and replace them with the original Mustache tags.

Please note when using Mustache or other placeholder tags, the translation engine would not know the context or meaning of a tag (i.e. the engine would not know if a tag will populate a name, or an address, or a color, or a numerical value, etc). This lack of context might affect the quality of the translation output.


# How to Translate Between Language Variants
Source: https://developers.deepl.com/docs/learning-how-tos/examples-and-guides/translating-between-variants

Learn how to translate between language variants, like British English and US English, using the DeepL API.

**This guide shows you:**

* How to translate between language variants (e.g., `en-US` to `en-GB`, `pt-PT` to `pt-BR`)
* Which method to choose: Write API, style rules, or custom instructions
* An example workflow for converting American English to British English

***

## Methods for translating between variants

You can use the DeepL API to translate between variants of the same language using 3 methods:

### 1. DeepL Write API

Use the [/write/rephrase](/docs/translate/write-quickstart) endpoint to rephrase text into the target language variant.

**When to use this:**

* You're translating shorter texts (headlines, product names, brief descriptions)
* You want high-quality rephrasing alongside variant translation

```bash Example cURL request theme={null}
curl -X POST 'https://api.deepl.com/v2/write/rephrase' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "text": ["Check out the new fall colors!"],
  "target_lang": "en-GB"
}'
```

```json Example response theme={null}
{
  "improvements": [
    {
      "text": "Check out the new autumn colours!",
      "detected_source_language": "en",
      "target_language": "en-GB"
    }
  ]
}
```

> [!WARNING]
>
> For longer texts, the Write API may rephrase and enhance content beyond simple variant conversion. If you need to maintain the exact structure while only updating locale-specific spelling and grammar, use another method.
>
> Please note that currently, the methods outlined below are not fully supported for this use case and may not always perform as intended. We encourage you to conduct your own evaluations.

### 2. Style rules with custom instructions

Create a reusable [style rule list](/docs/customize/using-style-rules) with attached `custom_instructions` describing the desired variant translation.

**When to use this:**

* You need to maintain the text's content between variants as precisely as possible
* You need consistent variant transformations across many translation requests
* You want to reuse the same variant rules without repeating the custom instructions

```bash Example cURL request theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "text": ["I went to the pharmacy."],
  "target_lang": "en-GB",
  "style_id": "your-style-rule-id"
}'
```

```json Example response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "I went to the chemist's."
    }
  ]
}
```

> [!NOTE]
>
> Glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them.
>
> Clients using the `api-us.deepl.com` endpoint will not be able to access glossaries or style rules created in the UI at this time.

### 3. Per-request custom instructions

Add [custom\_instructions](/api-reference/translate/request-translation#body-custom-instructions) describing the desired variant translation directly into your `/translate` requests.

**When to use this:**

* You need to maintain the text's content between variants as precisely as possible
* You need ad-hoc, one-off translations with specific variant requirements
* You don't want to manage separate style rules

```bash Example cURL request theme={null}
curl -X POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
--header 'Content-Type: application/json' \
--data '{
  "text": ["I went to the pharmacy."],
  "target_lang": "en-GB",
  "custom_instructions": ["translate to British English"]
}'
```

```json Example response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "I went to the chemist's."
    }
  ]
}
```

You can specify up to 10 custom instructions per request, each with a maximum of 300 characters.

***

## Next steps

Now that you understand how to translate between language variants:

* **Try it yourself:** Test out style rules and custom instructions in the [text translation API playground](/api-reference/translate/request-translation?playground=open)
* **Learn about the Write API:** Explore the [/write/rephrase endpoint](/docs/translate/write-quickstart) for high-quality variant translation and rephrasing
* **Manage reusable rules:** Learn how to create [style rules](/docs/customize/using-style-rules) for systematic variant transformations
* **Improve translation quality:** Understand how [the context parameter](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter) can enhance ambiguous translations


# Alpha and beta features
Source: https://developers.deepl.com/docs/resources/alpha-and-beta-features

Learn more about alpha and beta features in the DeepL API and how to best make use of them.

You might see API features in the documentation that are labeled as "alpha" or "beta". You can find the official definition in our terms and conditions ([section 3.1.5](https://www.deepl.com/en/pro-license)):

> 3.1.5 DeepL is free to provide customers with additional functions in alpha or beta versions on a test basis ("Test Functions"). These Test Functions are marked as such or as alpha or beta. Test Functions are not the subject of this Agreement. DeepL may make them available voluntarily to all or individual customers and the Customer is not obliged to make any payment for the use of Test Functions. Test Functions are intended for test use by the Customer and evaluation by DeepL. They are not final products or features and may contain bugs or other inaccuracies. DeepL can change, adapt or discontinue the Test Functions at any time.

In summary, features labeled as alpha or beta:

* Are not intended to be used in production
* Could be deprecated by DeepL at any time and without advance notice
* Could be changed in a way that breaks API clients relying on them at any time and without advance notice

Please keep this in mind when exploring or testing features labeled as alpha or beta.


# API Status Page
Source: https://developers.deepl.com/docs/resources/api-status-page

Monitor the operational status and availability of the DeepL API

The [DeepL Status Page](https://status.deepl.com) provides a real-time, [API-specific view](https://status.deepl.com/?tab=api) of the operational status of the DeepL API. The same page also covers DeepL's other services, along with incident reports and upcoming maintenance.

## What you can check

* **Current status** of all API services across all supported regions
* **90-day availability** history per service group (Translation, Write, Document Translation, Glossaries, and more)
* **Active and past incidents** affecting the API
* **Pro and Free API tier** status separately

## When to check

* If you're receiving HTTP 5xx errors from the API
* If you're experiencing elevated latency or timeouts
* Before investigating issues in your own integration — confirm the API is operational first

> Go to the API Status Page
>
> [Open](https://status.deepl.com/?tab=api)

> [!NOTE]
>
> For the status of all DeepL services (including web, desktop apps, and non-API products), see [status.deepl.com](https://status.deepl.com).


# Breaking changes (Change Notices)
Source: https://developers.deepl.com/docs/resources/breaking-changes-change-notices

Planned DeepL API deprecations and breaking changes that may affect your integration, with the notice for each.

In this section, we'll outline **planned deprecations and breaking changes** that might affect applications using the DeepL API.

To learn about new releases, please see the [Release notes](/docs/resources/release-notes) page.

> **[July 2024: Deprecation of insecure cipher suites](/docs/resources/breaking-changes-change-notices/july-2024-deprecation-of-insecure-cipher-suites)**

> **[March 2025: Deprecating GET requests to /translate and authenticating with auth\_key](/docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key)**

> **[November 2025: Deprecating query parameter and request body authentication](/docs/resources/breaking-changes-change-notices/november-2025-deprecation-of-legacy-auth-methods)**


# July 2024: Deprecation of insecure cipher suites
Source: https://developers.deepl.com/docs/resources/breaking-changes-change-notices/july-2024-deprecation-of-insecure-cipher-suites

DeepL deprecated insecure TLS cipher suites in 2024. Check which suites your TLS library negotiates if handshakes fail.

## Change Notice

On or after July 29, 2024, DeepL will deprecate support for insecure cipher suites. Affected customers will need to upgrade their TLS library so that it doesn't use a cipher suite that we’ll be deprecating.

If you are using an insecure cipher suite and do not make this update, you’ll no longer be able to use the DeepL API from the deprecation date onward.

> [!NOTE]
>
> Update on August 8, 2024: The deadline for this cipher deprecation has been extended to Monday, September 2, 2024.
>
> Please be sure to update your applications before September 2. We will not be able to extend the deadline any further.

### Which cipher suites are being deprecated for the DeepL API?

On or after July 29, 2024, we will be deprecating the following three cipher suites:

* TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA384 (0xc028)
* TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA (0xc014)
* TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA (0xc013)

This means that any application with a TLS library:

* That uses one of these cipher suites
* *And* does not support any of the cipher suites that will continue to be supported by DeepL

...will no longer be able to connect to the DeepL API.

### Why is DeepL doing this now?

The cipher suites that we’re deprecating have a historical track record of security weaknesses. They're still vulnerable to attacks that may enable a bad actor to decrypt data. We consider this to be an unacceptable security risk, especially given our commitment to keeping our customers’ data secure.

After deprecating the ciphers listed above, the DeepL API will accept the same set of cipher suites supported by our web translator ([deepl.com](https://www.deepl.com)) today.

### What happens if a user continues to use a deprecated cipher suite?

If you continue to use one of the cipher suites we’re deprecating, you won’t be able to access the DeepL API. This means that, for example, CAT tool plugins would no longer work properly.

### What cipher suites will be supported after deprecation?

We will continue to support the following cipher suites after deprecation:

* TLS 1.3 (suites in server-preferred order)
  * TLS\_AES\_256\_GCM\_SHA384 (0x1302)
  * TLS\_CHACHA20\_POLY1305\_SHA256 (0x1303)
  * TLS\_AES\_128\_GCM\_SHA256 (0x1301)
* TLS 1.2 (suites in server-preferred order)
  * TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384
  * TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256

### What action should I take so that I’m not affected?

**If you’re a developer of your own application with the DeepL API:**

* Ensure the TLS library you’re using supports one of the ciphers listed above

If you’re using a third-party plugin that is powered by the DeepL API:

* Update to the most recent version of the plugin Ask the plugin provider to upgrade their TLS library so that one of the cipher suites listed above is supported

### How can I test my application after making changes to ensure I’m using a supported cipher suite?

> [!NOTE]
>
> September 2024 update: because the cipher deprecation has been carried out according to schedule, the endpoint below is obsolete and is no longer available for use.

We created a test endpoint at `api-test-tls.deepl.com` that only supports the cipher suites that will still be available after the deprecation of insecure suites.

You can send a test request to this endpoint to be sure that you’re using a supported cipher suite. If you receive a translation response back from the DeepL API, then you should not be affected by the deprecation.

Below is an example cURL request using the test endpoint that Pro API users can use. Please remember to replace the `[yourAuthKey]` placeholder with your API key.

```bash theme={null}
curl -X POST 'https://api-test-tls.deepl.com/v2/translate' \
  --header "Authorization: DeepL-Auth-Key [yourAuthKey]" \
  --header "Content-Type: application/json" \
  --data \
'{
  "target_lang": "DE",
  "text" : ["Hello, world!"]
}'
```


# March 2025: Deprecating GET requests to /translate and authenticating with auth_key
Source: https://developers.deepl.com/docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key

DeepL deprecated GET requests to /translate and auth_key authentication in March 2025. Use POST with an Authorization header.

> [!NOTE]
>
> **Important:** The deprecations described on this page apply to both the `v1` (CAT tool) and `v2` API versions.

## Change Notice

On or after March 14, 2025, DeepL will deprecate two little-used API features.

* **You will no longer be able to send GET requests or query parameters to the**`/translate`**endpoint.** Going forward, `/translate` will accept only POST requests with data included in the request body.
* **You will no longer be able to authenticate a request to any endpoint by sending an API key in a query parameter.** Instead, send your API key in an HTTP header named `Authorization` .
* **If you use one of DeepL's officially-supported client libraries, you won't be negatively affected by the breaking changes and do not need to update your application.** Specifically, we've confirmed the following client library versions:
  * [deepl-php](https://github.com/deeplcom/deepl-php): 1.0.0+
  * [deepl-python](https://github.com/deeplcom/deepl-python): 1.0.0+
  * [deepl-java](https://github.com/DeepL/deepl-java): 1.0.0+
  * [deepl-dotnet](https://github.com/DeepL/deepl-dotnet): 1.0.0+
  * [deepl-node](https://github.com/DeepL/deepl-node): 1.1.0+
  * [deepl-rb](https://github.com/DeepL/deepl-rb): 3.0.0+ (the first version where DeepL took over ownership of the Ruby client library)

### Use POST for /translate

Going forward, you will need to send requests to the `/translate` endpoint using POST, not GET. This also means you will not be able to send such requests using only a URL. You will need to send data in the request body, not in query parameters.

[This example from the documentation](/api-reference/translate/request-translation) shows an HTTP POST request to translate the English sentence "Hello, world!" into German.

```HTTP theme={null}
POST /v2/translate HTTP/2 
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
Content-Length: 45
Content-Type: application/json
{"text":["Hello, world!"],"target_lang":"DE"}
```

Going forward, the API will reject a GET request like this.

```HTTP theme={null}
GET /v2/translate?text=Hello%2C%20world!&target_lang=DE HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
```

Similarly, the API will reject a request made with a URL and query string.

```
https://api.deepl.com/v2/translate?auth_key=yourAuthKey&text=Hello%2C%20world!&target_lang=DE
```

### Authenticate with an HTTP header

Going forward, you will need to authorize any API request, to any endpoint, by including your API key in an HTTP header named `Authorization`, like this:

```HTTP theme={null}
Authorization: DeepL-Auth-Key [yourAuthKey]
```

See the example above. For detailed information on authorization and how to use the `Authorization` header, please see [the documentation](https://developers.deepl.com/docs/getting-started/auth).

Going forward, you will not be able to authorize any request, to any endpoint, by including your API key in an `auth_key` query parameter.

### Why is DeepL doing this now?

#### Use POST for /translate

It is a standard API practice to use GET to request data and POST to send data. To request a translation, one must send data, making POST the customary choice. By disallowing GET and query params for this endpoint, we bring our API in line with industry best practices.

Additionally, data sent in query parameters is less secure than data sent in a POST body, as URLs with query parameters may be stored in browser history, discovered in logs, and more. This change helps us make the API more efficient and more private for everyone.

#### Authenticate with an HTTP header

Similarly, the API best practice is to authenticate a request by including the API key in an HTTP header. Sending an API key in a GET request or in a URL risks exposing the API key to the public via logs or other means. For privacy and security reasons, we must disallow this practice.

### What if I continue to use a deprecated feature?

After the date above, translation requests that use GET or query parameters will fail. Requests to any API endpoint that attempt to authenticate with the old `auth_key` parameter will fail as well.

### What action should I take so that I’m not affected?

If you develop your own application using the DeepL API:

* Ensure your code is not using either of the deprecated features.

If you’re using a third-party plugin that is powered by the DeepL API:

* Update to the most recent version of the plugin. If you experience trouble, contact the plugin provider to make sure they are aware of these deprecations.

For further questions, please visit [our support page](https://support.deepl.com).


# November 2025: Deprecation of query parameter and request body authentication
Source: https://developers.deepl.com/docs/resources/breaking-changes-change-notices/november-2025-deprecation-of-legacy-auth-methods

DeepL is removing auth_key query parameter and request body authentication. Move to the Authorization header before the deadline.

## Change Notice

> [!NOTE]
>
> Update: The deadline for this deprecation has been extended to January 15th, 2026.

On November 1st, 2025, DeepL will fully obsolesce support for providing authentication information in an `auth_key` query parameter or in an `auth_key` field of the request body.

Deprecation of this feature was previously announced in [March 2025](/docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key), but we have continued to support it temporarily to allow more time for customers to complete the migration.

You will no longer be able to authenticate a request to any endpoint by sending an API key in a query parameter or request body. Instead, send your API key in an HTTP header named `Authorization`.

* **You will no longer be able to authenticate a request to any endpoint by sending an API key in a query parameter or in the request body.** Instead, send your API key in an HTTP header named `Authorization` .
* **If you use one of DeepL's officially-supported client libraries, you won't be negatively affected by the breaking changes and do not need to update your application.** Specifically, we've confirmed the following client library versions:
  * [deepl-php](https://github.com/deeplcom/deepl-php): 1.0.0+
  * [deepl-python](https://github.com/deeplcom/deepl-python): 1.0.0+
  * [deepl-java](https://github.com/DeepL/deepl-java): 1.0.0+
  * [deepl-dotnet](https://github.com/DeepL/deepl-dotnet): 1.0.0+
  * [deepl-node](https://github.com/DeepL/deepl-node): 1.1.0+
  * [deepl-rb](https://github.com/DeepL/deepl-rb): 3.0.0+

Going forward, you will need to authorize any API request, to any endpoint, by including your
API key in an HTTP header named `Authorization`, like this:

```
Authorization: DeepL-Auth-Key [yourAuthKey]
```

For detailed information on authorization and how to use the Authorization header, please see the [documentation](https://developers.deepl.com/docs/getting-started/auth).
Going forward, you will not be able to authorize any request, to any endpoint, by including your API key in an `auth_key` query parameter or an `auth_key` field of the request body.

### Why is DeepL doing this now?

The API best practice is to authenticate a request by including the API key in an HTTP header. Sending an API key in a GET request or in a URL risks exposing the API key to the public via logs or other means. For privacy and security reasons, we must disallow this practice.

### What if I continue to use non-header authentication?

After the date above, translation requests that attempt to authenticate with an `auth_key` query parameter or an `auth_key` field in the request body will fail with a `403 Forbidden` response.

### What action should I take so that I’m not affected?

If you develop your own application using the DeepL API:

* Ensure your code is not using either of the deprecated features.

If you’re using a third-party plugin that is powered by the DeepL API:

* Update to the most recent version of the plugin. If you experience trouble, contact the plugin provider to make sure they are aware of these deprecations.

For further questions, please visit [our support page](https://support.deepl.com).


# Contact
Source: https://developers.deepl.com/docs/resources/contact

Find the right DeepL channel to get help with our API.

Support for the DeepL API is split across a few channels.

## Where to send your request

| **What you need** | **Where to go** |
| - | - |
| Discussion and knowledge sharing about the API | [DeepL Developer Community on Discord](https://discord.gg/deepl) |
| Account, subscription, billing, or plan changes | [Submit a support request](https://support.deepl.com/hc/en-us/requests/new) |
| Pricing, volume plans, or enterprise agreements | [Contact DeepL sales](https://www.deepl.com/en/contact-us) |
| A security vulnerability | Email [security@deepl.com](mailto:security@deepl.com). A PGP public key is published in [`SECURITY.md`](https://github.com/DeepL/api-docs/blob/main/SECURITY.md) |
| Issues with the documentation | [Open an issue on `DeepL/api-docs`](https://github.com/DeepL/api-docs/issues) |
| DeepL API availability and status | [DeepL API status page](https://status.deepl.com/?tab=api) |
| General answers | [DeepL Help Center](https://support.deepl.com/hc/en-us) |

## Before you open a support request

Include the following to help us get you the fastest possible answer:

* The `X-Trace-ID` response header from a failing request. DeepL API responses include this header, and it identifies that exact request in DeepL's logs
* The HTTP status code and the JSON `message` from the response body
* The endpoint you called
* The email address your subscription is linked to

Never include an API key or sensitive content in your message. If a key has been exposed, [deactivate it immediately](/docs/admin/managing-api-keys).

## Company details

DeepL API products are provided by DeepL SE. Full publisher information is available on the [DeepL publisher page](https://www.deepl.com/publisher).


# Developer Community
Source: https://developers.deepl.com/docs/resources/deepl-developer-community

Join the official DeepL developer community on Discord to ask questions and talk to other developers building on the API.

The official DeepL Developer Community is on [Discord](https://discord.gg/deepl) and open for everyone to join. It's a friendly, collaborative space to discuss everything DeepL, development, AI, tech and more!

![](https://mintcdn.com/deepl-c950b784/F1KSPiHPBwcCY4pE/_assets/images/discord-logo-black.png?fit=max\&auto=format\&n=F1KSPiHPBwcCY4pE\&q=85\&s=94b505dd1ae8ea9e10d92e0ade7d09b9)

The community is a place to:

* Introduce yourself and connect with other DeepL community members
* Share what you're currently working on and how you're integrating DeepL into your software projects
* Join upcoming live events and webinars exclusive to the community
* Ask for coding help and tips on development best practice, as well as offering your own help and experience

[Join the Discord community here!](https://discord.gg/deepl)


# Language release process
Source: https://developers.deepl.com/docs/resources/language-release-process

Here's what API users can expect when DeepL adds translation support for a new language or language variant.

On a regular basis, DeepL adds translation support for new languages or language variants. In this article,
we describe the process we'll follow with a new language or variant release.

## Language codes follow BCP 47

DeepL language codes follow [BCP 47](https://www.rfc-editor.org/rfc/rfc5646). A language code always
includes a base language subtag (e.g. `en`, `zh`), and may include additional subtags for script, region,
or variant where needed to distinguish variants. For example:

* `EN-US`, `PT-BR` -- region subtag to distinguish regional variants.
* `ZH-HANS`, `ZH-HANT` -- script subtag to distinguish writing systems.

BCP 47 is an expansive standard, and language codes can vary significantly in structure and length. As DeepL
adds support for more languages and variants, new codes may use any combination of subtags permitted by the
spec. For example, codes like `sr-Cyrl-RS` or `sr-Latn-RS` (Serbian in Cyrillic vs. Latin script, as used in
Serbia) are valid BCP 47 codes -- while DeepL does not support these today, your integration should be able
to handle codes of this form if they are added in the future.

> [!WARNING]
>
> **Do not hardcode assumptions about the format of language codes.** For example, do not assume that language
> codes will always be exactly two letters, or that a hyphenated code will always be in the format `xx-YY`.
> Instead, always treat the `lang` codes returned by the [/languages endpoint](/api-reference/languages/retrieve-supported-languages) as
> opaque identifiers. If you need to parse language codes, use a BCP 47-compliant library rather than writing
> custom parsing logic -- the full spec includes subtags for script, region, variant, extensions, and private
> use, and partial implementations are a common source of bugs.

## What happens when a new language is released

### Language release process for v3/languages

The [`/v3/languages`](/api-reference/languages/retrieve-supported-languages) endpoint provides flexibility
to specify which languages are supported by different products and which features are supported by each
language. Languages are added individually to each API resource, and new languages may initially be flagged
as beta before they are stable.

### Language release process for v2/languages

> [!NOTE]
>
> The `/v2/languages` endpoint is deprecated, and may not be extended with all new languages we support.
> You should build your integration to use `/v3/languages` instead.

* We will add the language code for the newly supported language or variant to the list on the
  [Supported languages](/docs/getting-started/supported-languages) page in the API documentation. The list
  shows support for text and document translation.
* If a newly added language or variant supports both text and document translation, we will add the language
  or variant to the [`/v2/languages`](/api-reference/languages/retrieve-supported-languages) endpoint response. The variant code used
  depends on the characteristics of the variant:
  * In some cases, a variant is primarily used in a specific region, and so a region subtag is the best way
    to identify it (e.g. `EN-US`, `PT-BR`).
  * In other cases, a variant is used widely across multiple regions, and so a script subtag is more
    appropriate (e.g. `ZH-HANS`, `ZH-HANT`). The subtag structure will be selected by DeepL on a case-by-case
    basis following BCP 47 conventions.
* In cases where a new language code with a variant duplicates the behavior of an existing language code
  without a variant (e.g. `ZH-HANS` was recently added as a language code for translating into simplified
  Chinese, along with `ZH`):
  * In the [`/v2/languages`](/api-reference/languages/retrieve-supported-languages) endpoint response, we will continue to return both
    language codes in two separate dicts with the same value in the `"name"` field.
  * For backwards compatibility, we will continue to support the original language code (in this example,
    `ZH`) for text and document translation.
* We will add the language code for the newly supported language or variant to our
  [OpenAPI spec](https://github.com/DeepL/openapi/).


# OpenAPI spec
Source: https://developers.deepl.com/docs/resources/open-api-spec

How to fetch the OpenAPI specifications for the DeepL API

The DeepL API is described by an [OpenAPI specification](https://openapis.org/) for the REST endpoints and an [AsyncAPI specification](https://www.asyncapi.com/) for the streaming Voice API. Both are published in YAML and JSON.

Fetch them from this documentation site at a stable URL:

| **Spec** | **Format** | **URL** |
| - | - | - |
| REST API (source of truth) | YAML | [`/api-reference/openapi.yaml`](/api-reference/openapi.yaml) |
| REST API | JSON | [`/api-reference/openapi.json`](/api-reference/openapi.json) |
| Voice WebSocket API (source of truth) | YAML | [`/api-reference/voice/voice.asyncapi.yaml`](/api-reference/voice/voice.asyncapi.yaml) |
| Voice WebSocket API | JSON | [`/api-reference/voice/voice.asyncapi.json`](/api-reference/voice/voice.asyncapi.json) |

The JSON files are generated from the YAML sources, so treat the YAML as authoritative.

The same files are available on [GitHub](https://github.com/DeepL/api-docs/tree/main/api-reference) if you prefer to pin a revision.

You can use these specs to explore the API in tools like [Postman](https://www.postman.com/), or to auto-generate SDKs and code libraries using tools such as [Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/DeepL/api-docs/main/api-reference/openapi.yaml) or [OpenAPI Generator](https://openapi-generator.tech/).

> [!NOTE]
>
> Swagger's "Try it out" in-browser simulator creates valid curl requests, but requests will fail due to [CORS restrictions](/docs/best-practices/cors-requests).

If you encounter issues or have feature requests, [create an issue](https://github.com/DeepL/api-docs/issues).


# Privacy
Source: https://developers.deepl.com/docs/resources/privacy

Where to find DeepL's privacy policy, terms, and data security information, and what to plan for in your integration.

## Privacy Policies & Information

| **Document** | **Area** |
| - | - |
| [DeepL Privacy Policy](https://www.deepl.com/privacy) | What personal data DeepL processes, on what legal basis, and your rights |
| [DeepL Terms & Conditions](https://www.deepl.com/pro-license) | The contractual terms for using DeepL services |
| [Data security at DeepL](https://www.deepl.com/pro-data-security) | Additional information on data protections for paid plans |

## What this means for your integration

Plan the following into your integration rather than discovering it in production:

* **Data handling may differ between the Free and Pro plans.** Confirm which plan your key belongs to and check the terms above before development.
* **Understand data residency if required.** DeepL offers [Regional API endpoints](/docs/getting-started/regional-endpoints) for certain customers that guarantee data processing within specific geographies.

## Intended purpose

The DeepL API is intended to translate or otherwise process general documents or other content provided by the customer in accordance with this documentation. It is not intended for any high-risk application as defined in [Article 6 of the EU AI Act](https://artificialintelligenceact.eu/article/6/), including any applicable delegated acts adopted by the European Commission on the basis of that provision.

## Reporting a problem

Report suspected vulnerabilities to [security@deepl.com](mailto:security@deepl.com), using the PGP key published in [`SECURITY.md`](https://github.com/DeepL/api-docs/blob/main/SECURITY.md). For privacy requests and any other question about your data, see [Contact and support](/docs/resources/contact).


# Changelog
Source: https://developers.deepl.com/docs/resources/roadmap-and-release-notes

The latest features and improvements in the DeepL API, plus what's coming next

**In active development**

* Editing the contents of an existing [translation memory](/docs/customize/using-translation-memories) via API

**October 2026**

## October 20 - Style Profiles

* A [style profile](/docs/customize/using-style-profiles) bundles the glossaries, style rule lists, and translation memories you use together under a single ID. Pass one `style_profile_id` in [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) requests instead of the individual customization parameters, and update the profile when the bundle changes instead of your integration.
* DeepL applies the components that fit each request: the glossaries for the language pair, the style rule list for the target language, and the translation memory for the source language. A profile can't be combined with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold`, or `custom_instructions` in the same request.
* Create and manage profiles with the new [style profiles endpoints](/api-reference/style-profiles/list-all-style-profiles) under `/v3/style_profiles`.

## October 7 - Document Translation CSV Report

* The document translation report is a CSV export of usage with one row per translated document. Each row shows the document type, source and target language, input and billed characters (including any billing minimum applied), and whether a glossary was used. Use it to trace document translation usage to individual documents; see the [CSV export section of the usage data guide](/docs/admin/retrieving-usage-data#csv-export) for how to download it.
* Generally available on the API Enterprise plan. On the API Pro plan, it's available on request; contact your customer success manager to enable it.

## October 1 - Voice API: Catalan, Galician, Hindi, Malay, Tamil, French (Canadian), and Spanish (Latin American) Generally Available

* `ca` (Catalan), `gl` (Galician), `hi` (Hindi), `ms` (Malay), and `ta` (Tamil) have moved out of beta and are now generally available in the [Voice API](/docs/voice/overview) as source languages and as translation targets. The `fr-CA` (French, Canadian) and `es-419` (Spanish, Latin American) translation target variants have moved out of beta as well.
* These languages now appear in the [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) response without `include=beta`. Transcription for Catalan, Galician, Hindi, Malay, and Tamil is still provided by external service partners and stays marked `"external": true`, so `include=external` is still required to list it and the source language must be set explicitly (no auto-detection).
* Spoken terms are now also listed for `ca` and `gl` in the same response (`spoken_terms`, beta, `"external": true`); call with `include=beta&include=external` to see them.
* The `translated_speech` feature keeps beta status in the `GET /v3/languages` response for all Voice API languages; nothing changes for voice output in this release.
* See the [supported languages table](/docs/voice/supported-voice-languages) for the full list.

**September 2026**

## September 30 - JSON Placeholder Protection

* [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) protects brace-delimited placeholders in `json` documents by default: values such as `{stars}` or `{{userName}}` are kept verbatim instead of being translated along with the surrounding text. Set `input_conversion_options=version:1,json-placeholders:translate` to translate them instead.
* ICU MessageFormat skeletons such as `{count, plural, one {# item} other {# items}}` are always protected, with only the branch text translated, in both modes.

## September 30 - Voice API Spanish (Latin America)

* The [Voice API](/docs/voice/overview) now supports `es-419` (Spanish, Latin America) as a target-language variant for translation and translated speech, in beta. Translation is provided by DeepL; translated speech is provided by an external service partner.
* `es-419` translated speech is reported with `"external": true` and beta status in the [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) response, so call with `include=beta&include=external` to see it.
* See the [supported languages table](/docs/voice/supported-voice-languages) for the full Voice API language list.

## September 29 - New Document Formats (Beta) and Embedded Image Translation Controls

* [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now supports ten additional file formats, all currently in beta: `xlsm` (macro-enabled Excel), `zip` (SCORM e-learning packages), `vtt` (WebVTT subtitles), `yaml` / `yml`, `properties` (Java properties), `strings` (iOS/macOS strings), `md` / `markdown`, `resx` (.NET resources), `odt` (OpenDocument Text), and `rtf` (Rich Text Format).
* A new `input_conversion_options` parameter controls how the input document is converted before translation. The `suppress-image-types` option leaves specified types of images embedded in `pptx` documents untranslated. For example, `version:1,suppress-image-types:all` suppresses all embedded images, and `version:1,suppress-image-types:logo-photo` suppresses logos and photos only.
* See [document translation best practices](/docs/best-practices/document-translations) for format-specific guidance and known constraints.

## September 29 - Style Rules for Language Variants

* [Style rule lists](/docs/customize/using-style-rules) hold the configured rules and custom instructions DeepL applies when translating into one target language. A list could previously only be created for a root language such as `de`, and it applied to every variant of that language. You can now also create a list for a specific variant, such as `de-CH` or `en-GB`, so conventions that differ between variants stay separate.
* Set the variant code in the `language` field of [`POST /v3/style_rules`](/api-reference/style-rules/create-style-rule). A variant list applies when `target_lang` is that variant; root-language lists keep applying to all variants as before.
* Lists for `de-CH`, `fr-CA`, `pt-BR`, and `pt-PT` are generally available; lists for `de-DE`, `en-GB`, `en-US`, `es-419`, `es-ES`, `fr-FR`, `zh-Hans`, and `zh-Hant` are in beta. The current list and the status of each language are returned by [`GET /v3/languages?resource=style_rules&include=beta`](/docs/languages/using-the-languages-api).

## September 22 - New Voice API Languages: Catalan and Galician

* The [Voice API](/docs/voice/overview) now supports `ca` (Catalan) and `gl` (Galician) as source languages and as targets for translation and translated speech. Both are beta for the Voice API; they are already generally available for text and document translation. Translation is provided by DeepL; transcription and translated speech are provided by external service partners, so the source language must be set explicitly (no auto-detection).
* Both languages are marked `"external": true` on the `transcription` and `translated_speech` features in the [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) response. Because they are beta and external, call with `include=beta&include=external` to see them.
* See the [supported languages table](/docs/voice/supported-voice-languages) for the full list.

## September 22 - Hebrew, Slovenian, and Thai Translated Speech in the Voice API

* The [Voice API](/docs/voice/overview) now generates translated speech (voice output) for `he` (Hebrew), `sl` (Slovenian), and `th` (Thai), in beta. Transcription and translation for these languages were already supported; this adds synthesized audio.
* Translated speech for all three languages is provided by external service partners. In the [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) response, `translated_speech` is reported with `"external": true` and beta status. Call with `include=beta&include=external` to see it.
* See the [supported languages table](/docs/voice/supported-voice-languages) for the full list.

## September 20 - Quality Evaluation for Document Translation (Beta)

* A **quality evaluation** is a report on a translation DeepL has produced: for each segment it lists detected issues such as mistranslations, omissions, and fluency or style problems, with a severity and the character range the issue applies to. Use it to target human review at the segments that need it.
* Request one by setting `enable_quality_evaluation=true` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document). The upload response then returns a `quality_evaluation_job_id`, which you poll at [`GET /v1/quality-evaluations/{job_id}`](/api-reference/quality-evaluations/poll) to retrieve the report. See [Requesting a quality evaluation](/docs/best-practices/document-translations#requesting-a-quality-evaluation) for the full flow.
* Reports cover `docx`, `pptx`, `pdf`, `idml`, `xml`, `dita`, `mif`, and XLIFF 2.1 uploads, and a subset of the language pairs translation supports. Each report also returns a quality score, the source and translated text, and any applied glossary term pairs for every segment.
* In beta and available to select customers only. To have it enabled for your account, contact your customer success manager.

## September 11 - Speaker Match Voice for the Voice API

* **Speaker match** is a new voice option for [Voice API](/docs/voice/overview) translated speech: instead of one of the preset voices, the synthesized audio uses a voice close to the original speaker's. Set [`target_media_voice`](/api-reference/voice/request-session) to `match` on the session request.
* Speaker match is only available for target languages whose translated speech is provided by DeepL, not for languages provided through external service partners. Requesting it for any other target language is not an error: that language falls back to a preset voice. See the [supported languages table](/docs/voice/supported-voice-languages) for the full list.

## September 8 - Language Pair-Level CSV Report

* Usage broken down by source-target language pair can now be exported as a CSV report from the account UI. Select "Language pair-level report" from the "Download CSV usage report" dropdown on the [API Keys & Limits tab](https://www.deepl.com/your-account/keys) or the [API Usage tab](https://www.deepl.com/your-account/usage).
* Generally available on the API Enterprise plan. On the API Pro plan, it's available on request; contact your customer success manager to enable it.
* See the [CSV export section of the usage data guide](/docs/admin/retrieving-usage-data#csv-export) for report contents and supported time ranges.

## September 8 - Voice API French Variants: French (France) and French (Canadian)

* The Voice API now supports `fr-FR` (French, France) and `fr-CA` (French, Canadian) as target language variants for translation and translated speech (translated speech for both variants is in beta and uses the French voices). `fr-FR` is generally available; `fr-CA` is in beta for the Voice API (for text and document translation it has been generally available since July 17).
* Because `fr-CA` is beta, include `include=beta` when calling [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) to see it.
* See the [supported languages table](/docs/voice/supported-voice-languages) for the full Voice API language list.

## September 1 - Croatian and Tagalog Translated Speech in the Voice API

* The [Voice API](/docs/voice/overview) now generates translated speech (voice output) for `hr` (Croatian) and `tl` (Tagalog), in beta. Transcription and translation for these languages were already supported; this adds synthesized audio.
* Translated speech for both languages is provided by external service partners. In the [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) response, `translated_speech` is reported with `"external": true` and beta status — call with `include=beta&include=external` to see it.
* See the [supported languages table](/docs/voice/supported-voice-languages) for the full list.

**August 2026**

## August 18 - Custom Reporting Tags for the Voice API

* [Custom reporting tags](/docs/learning-how-tos/examples-and-guides/how-to-use-custom-reporting-tags), which attribute API usage to a team, project, or other category via the `X-DeepL-Reporting-Tag` request header, now work for the [Voice API](/docs/voice/overview) in addition to text translation. Send the header on the [session request](/api-reference/voice/request-session) and the whole session's usage is attributed to that tag.
* The [custom tag usage analytics endpoint](/api-reference/admin-api/get-custom-tag-usage-analytics) reports voice usage as `speech_to_text_minutes` and `speech_to_speech_minutes` alongside the existing character fields. Voice minutes are not included in `total_characters`.
* A tag can only be set on the session request, since the WebSocket connection carries no headers. To attribute audio to more than one tag, open a separate session per tag.

## August 11 - Translation Memory Management API

* You can now create, inspect, export, and delete [translation memories](/docs/customize/using-translation-memories) through the API. Translation memories store previously translated segments so the same source text produces consistent output across projects. Previously, the API could only list the translation memories on your account, and everything else had to be done in the DeepL UI.
* [`POST /v3/translation_memories/import`](/api-reference/translation-memory/import-a-translation-memory) creates a translation memory from a TMX file. The request declares the file and returns a signed upload URL plus a `job_id`; you upload the file to that URL and poll the job for the new `translation_memory_id`.
* [`POST /v3/translation_memories/{translation_memory_id}/export`](/api-reference/translation-memory/export-a-translation-memory) exports a translation memory as TMX, also as a background job.
* [`GET /v3/translation_memories/jobs/{job_id}`](/api-reference/translation-memory/retrieve-a-translation-memory-job) reports the status of both import and export jobs.
* [`GET /v3/translation_memories/{translation_memory_id}`](/api-reference/translation-memory/retrieve-a-translation-memory) retrieves a single translation memory, and [`GET /v3/translation_memories/{translation_memory_id}/segments`](/api-reference/translation-memory/list-translation-memory-segments) pages through its stored segments with cursor-based pagination.
* [`DELETE /v3/translation_memories/{translation_memory_id}`](/api-reference/translation-memory/delete-a-translation-memory) permanently deletes a translation memory and all of its segments.
* Reading requires an API key with the `translation_memories:read` scope; importing and deleting require `translation_memories:write`. See [permission scopes](/docs/admin/permission-scopes).
* Editing the contents of an existing translation memory is not yet supported. To change what a translation memory contains, import a new one.

## August 5 - Custom Tag-Level CSV Export

* Usage broken down by [custom reporting tag](/docs/learning-how-tos/examples-and-guides/how-to-use-custom-reporting-tags) can now be exported as a CSV report from the account UI, in addition to being available through the [custom tag usage analytics endpoint](/api-reference/admin-api/get-custom-tag-usage-analytics) in the Admin API. Custom tags attribute API usage to a team, project, or other category via the `X-DeepL-Reporting-Tag` request header.
* The "Download CSV usage report" button on the [API Keys & Limits tab](https://www.deepl.com/your-account/keys) and the [API Usage tab](https://www.deepl.com/your-account/usage) is now a dropdown: select "Custom tag-level report" or "API key-level report".
* See the [CSV export section of the usage data guide](/docs/admin/retrieving-usage-data#csv-export) for supported time ranges and report contents.

**July 2026**

## July 22 - Admin API Available to All API Pro Subscribers

* The [Admin API](/docs/admin/overview#the-admin-api), which lets admins [manage developer keys](/api-reference/admin-api/managing-developer-keys/create-key) programmatically and retrieve [usage analytics](/docs/admin/retrieving-usage-data#admin-api-analytics) grouped by API key or custom tag, is now available to all API Pro subscribers, in addition to API Growth and API Enterprise subscribers.
* Previously, API Pro subscribers had to request access through their customer success manager or DeepL support. No action is required to enable access.
* Create an admin key in the ["Admin API Keys" subtab](https://www.deepl.com/your-account/keys?keyType=admin) of your account to get started. See [Managing API Keys in the Account UI](/docs/admin/managing-api-keys#manage-admin-api-keys) for instructions, or jump into the [Admin API Quickstart](/docs/admin/quickstart).

## July 17 - German (Swiss) and French (Canadian) Generally Available

* `de-CH` (German, Swiss) and `fr-CA` (French, Canadian) target language variants have moved out of beta and are now generally available for text and document translation.
* Characters translated into these languages are now billed and count against your character threshold, like other supported languages. During the beta phase, they were not billed.
* See the [supported languages table](/docs/getting-started/supported-languages) for the full list of variants and their supported features.

## July 17 - Voice API Speech Output Generally Available

* **Speech-to-speech** (translated speech output) moves out of closed beta and is now **generally available**.
* See [understanding voice sessions](/docs/voice/understanding-voice-sessions#translated-speech) for how translated speech works and the [supported languages table](/docs/voice/supported-voice-languages) for language availability.

## July 16 - Combined Status Page

* DeepL now publishes a single [status page](https://status.deepl.com) covering all services, with a dedicated [API view](https://status.deepl.com/?tab=api) for real-time API status and incidents.

## July 14 - Watermarking for Document Translation

* [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now accepts an `enable_watermark` parameter. When set to `true`, a "Translated by DeepL" watermark is applied to the translated document.
* Supported for `docx` and `pdf` output only; the parameter is ignored for all other formats.
* See the [document translation](/api-reference/document#request-body-descriptions) overview page for parameter details.

## July 7 - New Document Formats and Higher File Size Limits

* [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now supports five additional file formats: `idml` (Adobe InDesign), `xml`, `json`, `dita` (DITA topics), and `mif` (Adobe FrameMaker).
* XLIFF support has been expanded to versions 1.2, 2.0, and 2.1 (previously 2.1 only).
* File size limits on DeepL API Pro have increased to 100 MB for Word (`.docx`), PowerPoint (`.pptx`), and PDF (`.pdf`). See [Usage and limits](/docs/resources/usage-limits) for the full per-format table.
* See [document translation best practices](/docs/best-practices/document-translations) for format-specific guidance and known constraints.

## July 2 - New Voice API Languages: Hindi, Malay, and Tamil

* The Voice API now supports `hi` (Hindi), `ms` (Malay), and `ta` (Tamil) in beta. Translation is provided by DeepL; transcription and translated speech are provided by external service partners.
* These languages are marked `"external": true` in the [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) response. Because they are beta and external, call with `include=beta&include=external` to see them.
* See the [supported languages table](/docs/voice/supported-voice-languages) for the full list.

**June 2026**

## June 29 - Spoken Terms API Management

* New [`/v3/spoken-terms`](/docs/customize/improving-transcription-with-spoken-terms) endpoints provide full API management for Spoken Terms collections, which improve transcription accuracy for company-specific terminology, acronyms, and proper names in the Voice API.
* Create, list, retrieve, update, and delete Spoken Terms collections programmatically. Each collection contains one or more term lists, with each term list holding terms for a single language.
* Key endpoints:
  * [`POST /v3/spoken-terms`](/api-reference/spoken-terms/create-spoken-terms-collection) - Create a new collection with term lists
  * [`GET /v3/spoken-terms`](/api-reference/spoken-terms/list-all-spoken-terms) - List all collections
  * [`GET /v3/spoken-terms/{spoken_terms_id}/entries`](/api-reference/spoken-terms/retrieve-spoken-terms-entries) - Retrieve terms for a specific language
  * [`PATCH /v3/spoken-terms/{spoken_terms_id}`](/api-reference/spoken-terms/edit-spoken-terms-details) - Update collection name or merge new terms
  * [`PUT /v3/spoken-terms/{spoken_terms_id}/term-lists`](/api-reference/spoken-terms/replace-or-create-term-list) - Replace or create a term list for a language
  * [`DELETE /v3/spoken-terms/{spoken_terms_id}`](/api-reference/spoken-terms/delete-spoken-terms) - Delete a collection
* This completes the API management capabilities announced in the May 19 Voice API Spoken Terms release. Previously, Spoken Terms could only be managed through [DeepL Home](https://www.deepl.com/en/voice/spoken-terms).

## June 24 - API Key Permissions General Availability

* [Understanding API Key Permissions](/docs/admin/api-key-permissions) are now generally available. Scope a developer API key to specific endpoints so it can perform only the operations you allow.
* Available on the API Pro, API Developer, API Growth, and API Enterprise plans.
* Assign scopes when [creating or editing a key](https://www.deepl.com/your-account/keys). A scoped key returns `403 Forbidden` on any endpoint its scopes don't cover.

## June 23 - Multiple Glossaries per Translation Request

* [`POST /v2/translate`](/api-reference/translate/request-translation) and [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now accept a `glossary_ids` parameter, allowing you to apply up to 5 glossaries to a single translation request.
* Useful when terminology is split across multiple glossaries (for example, a shared brand glossary plus a project-specific glossary) that you want applied together without merging them.
* `glossary_ids` requires `source_lang` and is mutually exclusive with the existing `glossary_id` parameter. Every listed glossary must contain a dictionary for the requested language pair.
* See the [text translation](/api-reference/translate/request-translation) and [document translation](/api-reference/document/upload-and-translate-a-document) overview pages for parameter details.

## June 17 - `latency_optimized` Now Supported for All Features

* The `latency_optimized` model type is now fully compatible with all Translate API features, including:
  * [Tag handling v2](/docs/translate/translating-xml) (`tag_handling_version=v2`)
  * [Style rules](/docs/customize/using-style-rules) (`style_id`)
  * [Custom instructions](/docs/customize/custom-instructions) (`custom_instructions`)
  * [Translation memories](/docs/customize/using-translation-memories) (`translation_memory_id`)
  * All language pairs, including languages previously restricted to `quality_optimized`
* Previously, combining `model_type=latency_optimized` with these features would return an error. These restrictions have been removed.

## June 15 - API Key Permissions (Private Beta)

* Developer API keys can now be scoped to specific endpoints, so a key can be limited to, for example, translating text or reading glossaries. See [Understanding API Key Permissions](/docs/admin/api-key-permissions).
* Assign one or more scopes when [creating or editing a key](https://www.deepl.com/your-account/keys). A scoped key returns `403 Forbidden` on any endpoint its scopes don't cover.
* Currently in private beta for select customers. To request access, contact your customer success manager or [DeepL support](https://support.deepl.com/hc/en-us/requests/new).
* Not yet supported for the Voice API; Voice scopes will follow in a future update.

## June 8 - Style Rules and Translation Memories for Document Translation

* [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now accepts `style_id`, `translation_memory_id`, and `translation_memory_threshold`, bringing document translation in line with the parameters already available on text translation.
* `style_id` applies a configured [style rule list](/docs/customize/using-style-rules) to the document translation.
* `translation_memory_id` and `translation_memory_threshold` work as on text translation: pass a translation memory ID to apply stored translations, and set a threshold (0-100) to control how closely source text must match a stored segment. See the [translation memories guide](/docs/customize/using-translation-memories).

## June 5 - Voice API Spoken Terms on External-Provider Languages

* Spoken terms are now supported on languages whose transcription is provided by external service partners, in addition to languages transcribed by DeepL. The feature remains in beta on all supported languages.
* External-provider languages are marked `"external": true` in the [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) response. Call with `include=beta&include=external` to see the full list.
* See [Voice API Customization](/docs/voice/overview#customization) for usage details.

## June 3 - Docs MCP Server

* DeepL's developer documentation now exposes an MCP server at `https://developers.deepl.com/mcp`.
* This enables AI tools to search the docs directly and get source-grounded answers about the DeepL API, with no API key required.
* See the [Docs MCP Server](/docs/getting-started/docs-mcp-server) page for setup instructions.

## June 1 - API Status Page

* Launched the [DeepL API Status Page](https://status.deepl.com/?tab=api), a dedicated dashboard for monitoring the operational status and availability of the DeepL API.
* View real-time status and 90-day availability for all API services across all supported regions.
* Supports both Pro and Free API tiers.
* Available in 19 languages.

**May 2026**

## May 27 - Custom Reporting Tags in deepl-rb

* The Ruby client library [`deepl-rb`](https://github.com/DeepL/deepl-rb) v3.8.0 now accepts an `additional_headers` argument on `translate` calls, so you can send `X-DeepL-Reporting-Tag` for usage reporting.
* See [Sending Custom Reporting Tags with Client Libraries](/docs/learning-how-tos/cookbook/sending-custom-reporting-tags-from-client-libraries) for the updated Ruby snippet.

## May 26 - API Usage Logger Cookbook

* Added a new cookbook, [API Usage Logger](/docs/learning-how-tos/cookbook/api-usage-logger), showing how to capture per-request DeepL API usage data (billed characters, language pairs, reporting tags, API keys, errors) and explore it through a local Streamlit dashboard.
* Source code on GitHub: [`DeepL/deepl-api-usage-logger`](https://github.com/DeepL/deepl-api-usage-logger).

## May 20 - Custom Tag Usage Analytics

* Added [`GET /v2/admin/analytics/custom-tags`](/api-reference/admin-api/get-custom-tag-usage-analytics) to the Admin API, allowing admins to retrieve usage statistics broken down by custom tags.
* Supports `aggregate_by=period` (default) to aggregate usage over the full date range, or `aggregate_by=day` for daily breakdowns.
* Results are paginated; use the `next_page` integer from the response as the `page` parameter in subsequent requests.

## May 19 - Voice API Spoken Terms

* New optional `spoken_terms_id` parameter on [`POST /v3/voice/realtime`](/api-reference/voice/request-session) to improve transcription of frequently used terms like company-specific terminology, acronyms, product names, and team member names.
* Spoken terms are currently in beta, supported for 18 source languages. Manage them in [DeepL Home](https://www.deepl.com/en/voice/spoken-terms); API management will follow in a future update.
* The new `spoken_terms` feature and the existing `translated_speech` feature are now exposed as beta in [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api), so clients can discover language support programmatically.
* Not yet supported for transcription provided by external service partners (languages marked with ⎋). See [Voice API Customization](/docs/voice/overview#customization) for details.

## May 18 - v3/languages General Availability

* [`GET /v3/languages`](/docs/languages/using-the-languages-api) and [`GET /v3/languages/resources`](/api-reference/languages/retrieve-resources) are now generally available.
* **`/v2/languages` and `/v2/glossary-language-pairs` are now deprecated.** Migrate to `/v3/languages`. See the [migration guide](/docs/languages/migrating-from-v2-languages) for details.

**April 2026**

## April 30 - German (Swiss) and French (Canadian) Beta

* `de-CH` (German, Swiss) and `fr-CA` (French, Canadian) have moved to beta.
* During the beta phase, characters translated into these languages are not billed and do not count against your character threshold. Prior to April 30, these languages were generally available and billed normally.
* See [supported languages](../getting-started/supported-languages) for the complete language list.

## April 17 - New Language Variants: German (Swiss) and French (Canadian)

* Added support for two new target language variants: `de-CH` (German, Swiss) and `fr-CA` (French, Canadian) for text translation. These variants are now generally available.
* Use these language codes as `target_lang` values to produce translations tailored to Swiss German and Canadian French.
* Document translation support for these variants will follow in a future release.
* See [supported languages](../getting-started/supported-languages) for the complete language list.

## April 15 - Voice API General Availability

* The [Voice API](/docs/voice/overview) is now available to all DeepL customers with a paid API subscription. This API provides real-time speech transcription and translation and can be used with existing DeepL API keys.

## April 9 - Translation Memory API

* Added support for [translation memories](/docs/customize/using-translation-memories) in the DeepL API. Translation memories store previously translated segments so the same source text produces consistent output across projects .
* New `translation_memory_id` and `translation_memory_threshold` parameters on the [text translation endpoint](/api-reference/translate/request-translation) — pass a translation memory ID to apply stored translations, and set a threshold (0-100) to control how closely source text must match a stored segment.
* New [`GET /v3/translation_memories`](/api-reference/translation-memory/list-translation-memories) endpoint to retrieve translation memories associated with your account.
* Support for uploading, modifying, and deleting translation memories via the API will follow.

## April 2 - Voice API Language Expansion

* Added 6 new languages to the [Voice API](/docs/voice/overview) for transcription: Bengali (`bn`), Croatian (`hr`), Dutch (`nl`), Irish (`ga`), Maltese (`mt`), and Tagalog (`tl`). Five of these are provided by external service partners; Dutch is provided by DeepL.
* All supported voice languages can now be used as source languages for transcription. Previously, source language selection was restricted to a subset of the supported languages.

**March 2026**

## March 31 - Write API Improvements

* Improved overall quality of the models used in [DeepL API for Write](/api-reference/improve-text/)
* Expanded Write `target_lang` support to Japanese (`JA`), Korean (`KO`) and simplified Chinese (`ZH` or `zh-Hans`)
* Expanded Write support for `writing_style` and `tone` to Spanish (`ES`), Italian (`IT`), French (`FR`), Portuguese (`pt-PT`) and Brazilian Portuguese (`pt-BR`)
* Allow sending Write texts in multiple source languages in the same request when no `target_lang` is set

## March 26 - Expanded Style Rules API

* Added 5 new endpoints for style rule list operations: `POST /v3/style_rules`, `GET /v3/style_rules/{style_id}`, `PATCH /v3/style_rules/{style_id}`, `DELETE /v3/style_rules/{style_id}`, and `PUT /v3/style_rules/{style_id}/configured_rules`.
* Added 4 new endpoints for managing custom instructions within style rule lists: `POST /v3/style_rules/{style_id}/custom_instructions`, `GET /v3/style_rules/{style_id}/custom_instructions/{instruction_id}`, `PUT /v3/style_rules/{style_id}/custom_instructions/{instruction_id}`, and `DELETE /v3/style_rules/{style_id}/custom_instructions/{instruction_id}`.
* See the full API reference [here](/docs/customize/using-style-rules).

## March 24 - Write API Character Count Fix

* Fixed an issue where some [DeepL API for Write](/api-reference/improve-text/) requests under-counted usage.
* All characters in Write requests are now correctly counted for billing and reporting purposes.

**February 2026**

## February 18 - Additional Languages in `v2/languages`

* New languages added to the [v2/languages endpoint](/api-reference/languages/retrieve-supported-languages), bringing totals to **101 source languages** and **106 target languages**.
* These languages were already supported for translation; this change improves automatic discoverability for API clients.
* Note: 12 supported languages using three-letter base codes (e.g. ACE, CEB, CKB) are not yet included in `v2/languages` for backwards compatibility, but will be available in the upcoming `v3/languages` endpoint.

**January 2026**

## January 27 - Voice Usage Limits on Developer Keys

* Added `speech_to_text_milliseconds` to the `/v2/admin/developer-keys/limits` endpoint and the `ApiKey` response schema, so admins can set and read per-key voice usage limits alongside character limits.
* See the [Admin API overview](/docs/admin/overview) for usage.

## January 20 - Legacy Auth Deprecation

Query parameter and request body authentication methods are now [deprecated](/docs/resources/breaking-changes-change-notices/november-2025-deprecation-of-legacy-auth-methods).

* **API Free users**: All requests using legacy auth now return `403 Forbidden`.
* **API Pro users**: Brownout period active with intermittent `403` responses. Full deprecation in early February 2026.

Use the `DeepL-Auth-Key` header instead.

## January 19 - Voice API Speech-to-Speech (Closed Beta)

* New speech-to-speech capability in the [Voice API](/docs/voice/overview): synthesize translated audio (TTS output) alongside transcription and text translation in the same WebSocket session.
* New request parameters on [`POST /v3/voice/realtime`](/api-reference/voice/request-session): `target_media_languages` (target languages for synthesized speech), `target_media_content_type` (audio format), and `target_media_voice` (voice selection).
* Translated speech is in closed beta and not included in standard API subscriptions.

## January 8 - 81 New Languages in GA

* Promoted all 81 beta languages to standard language support. These languages are now part of the main source and target language lists.
* These languages are compatible with all `model_type` values including `latency_optimized`.
* The `enable_beta_languages` parameter is maintained for backward compatibility but has no effect.

See [here](../getting-started/supported-languages) for the complete language list.

**December 2025**

## December 11 - Voice Usage in `/v2/usage` and Analytics

* `/v2/usage` now returns `speech_to_text_milliseconds_count` and `speech_to_text_milliseconds_limit` for API Pro users, so customers using the Voice API can monitor consumption against their plan.
* Each product usage item now includes `billing_unit`, `api_key_unit_count`, and `account_unit_count`, making per-product reporting consistent across characters and voice milliseconds.
* The same `speech_to_text_milliseconds` field was added to usage reports and analytics components used by the [Admin API analytics endpoint](/api-reference/admin-api/get-usage-analytics).

**November 2025**

## November 10 - Voice API Initial Release

* Initial release of the Voice API: `/v1/voice/realtime` (REST) and `/v1/voice/realtime/connect` (WebSocket) for real-time speech transcription and translation. The Voice API is generally available as of [April 15, 2026](#april-15---voice-api-general-availability).
* Published a new AsyncAPI specification (`voice.asyncapi.yaml` / `voice.asyncapi.json`) documenting the WebSocket streaming protocol. See the [WebSocket Streaming reference](/api-reference/voice/websocket-streaming).

## November 6 - HE, TH, and VI in `/v2/languages`

* Hebrew (`HE`), Thai (`TH`), and Vietnamese (`VI`) now appear in the [`/v2/languages`](/api-reference/languages/retrieve-supported-languages) response, since they support document translation in addition to text translation.

**2025**

## Q4 2025

* Added API reference for the Voice API
* Add contextual menu in the to make it easier to copy any API documentation page as context for AI tools
* Add support for style rules in the API to programmatically get your created style rules and translate with them.
* Overhauled the tag-handling algorithm that backs translation of XML and HTML in the DeepL API. To enable it and benefit from all the improvements, set the `tag_handling_version` parameter to `v2` in the text translation API. See [Translating XML](/docs/translate/translating-xml) for more information.
* Added new usage analytics endpoint in the Admin API, including key-level reporting. See [here](/api-reference/admin-api/get-usage-analytics) for more details
* Enabled support for multiple admins in an API subscription
* Added support for 75 new languages, initially through the `enable_beta_languages` parameter, for text and document translation. Beta languages are not billed during the beta phase and do not yet support glossaries or formality. See [here](../getting-started/supported-languages) for more information
* Added HE, TH and VI to the languages endpoint, since they are now also available in document translation
* Added 6 additional beta languages, for text and document translation. See the previous note about 75 new languages.
* Added a new parameter to the text translation API to allow custom instructions, making it possible to customize the translation behavior (e.g. \["Use a friendly, diplomatic tone"])
* Added support for JPEG and PNG images in [document translation](/api-reference/document/upload-and-translate-a-document), currently in Beta.

## Q3 2025

* Creation of an admin API, making it possible to manage API keys programmatically. See the [Admin API overview](/docs/admin/overview) for more information
* Added support for new language: ES-419 (Latin American Spanish). For this release, this language will be available for the API in next-gen models only. See [here](../getting-started/supported-languages) for more information.
* Refreshed our API documentation and added new try-it explorers to support interacting with our APIs. See [here](/api-reference) to try it out!

## Q2 2025

* Added support for new language: TH (Thai). For this release, this language will only support text translation. See [here](../getting-started/supported-languages) for more information.
* Added support for new languages: HE (Hebrew) and VI (Vietnamese). For this release, these languages will be available for Pro v2 API in next-gen models only. See [here](../getting-started/supported-languages) for more information.
* Added improvements to API glossaries, including the ability to edit glossaries and create multilingual glossaries. Learn more [here](/api-reference/multilingual-glossaries/).
* Added new events to audit logs for Pro API customers (API key management, cost control and usage limit changes)
* Improvements to the `/usage` endpoint for Pro API customers ([API reference](/api-reference/usage-and-quota/check-usage-and-limits))
* Improvements to key-level usage reporting, making it possible to pull reports with a custom date range and to group data by calendar day. Learn more in the [usage data guide](/docs/admin/retrieving-usage-data#csv-export).

## Q1 2025

* Added support for API key-level usage limits, making it possible to set a character limit at the API key-level. Learn more [here](/docs/admin/managing-api-keys#set-a-key-level-usage-limit).
* DeepL API for Write is generally available to Pro API customers, making it possible to improve texts in (at the time of release) 6 different languages. Learn more and get started [here](/api-reference/improve-text/).

**2024**

## Q4 2024

* Added the `model_type` parameter, allowing users to translate text with DeepL's "next-gen" translation models. More information can be found [here](/docs/translate/understanding-model-types).

## Q3 2024

* Added the `show_billed_characters` parameter for text translation, allowing users to optionally include the number of billed characters in the API response. [Learn more here](/api-reference/translate/request-translation).
* Added support for a new language for text translation: ZH-HANT (Traditional Chinese). As of this initial release, document translation is not supported for Traditional Chinese. More information is available [here](/docs/getting-started/supported-languages).
* An official Ruby client library, evolved from a community-written library by Daniel Herzog. You can download it [here](https://rubygems.org/gems/deepl-rb) or find the source code on our [GitHub page](https://github.com/DeepL/deepl-rb).
* Added Romanian (`RO`) as a supported [glossary](/docs/customize/managing-glossaries) language.

## Q2 2024

* Added support for DOCX and PPTX document minification to the PHP client library, making it possible for users to translate documents that exceed DeepL's file size limit due to embedded media. [Learn more here](https://github.com/DeepL/deepl-php?tab=readme-ov-file#document-minification).
* Added support for API key-level usage reporting. More information is available in the [multiple API keys guide](https://developers.deepl.com/multiple-api-keys#download-a-report-with-key-level-usage).
* Launched DeepL Pro in [165 new markets](https://www.deepl.com/en/blog/deepl-pro-expands-165-new-markets), bringing the total number of markets where DeepL Pro is available to 228. This means users with billing addresses in these markets can create DeepL Pro API and Free API subscriptions.
* Added support for new glossary languages: DA (Danish), NB (Norwegian Bokmål), and Swedish (SV).
* Moved the `context` parameter from [alpha](/docs/getting-started/alpha-and-beta-features) status to general availability. More information about the context parameter is available in the "Request body descriptions" table [here](/api-reference/translate/request-translation).
* Added support for SRT (`srt`) files in [document translation](/api-reference/document/upload-and-translate-a-document).

## Q1 2024

* Added support for multiple API keys in a single account for Pro API and Free API users. More information is available in the [multiple API keys guide](https://developers.deepl.com/multiple-api-keys).
* Added support for a new language for text translation: AR (Arabic). As of this initial release, document translation is not supported for Arabic. More information is available [here](/docs/getting-started/supported-languages).
* Added support for Korean (KO) as a [glossary](/docs/customize/managing-glossaries) language, increasing the number of supported glossary language pairs from 55 to 66.

**2023**

## Q4 2023

* Added support for Microsoft Excel (`xlsx`) files in [document translation](/api-reference/document/upload-and-translate-a-document).
* Released the `context` parameter as an [alpha feature](/docs/getting-started/alpha-and-beta-features) for text translation (see [Request Body Descriptions table](/api-reference/translate/request-translation) for more information).

## Q3 2023

* Launched DeepL Pro in South Korea ([blog post here](https://www.deepl.com/en/blog/deepl-pro-available-in-south-korea)). This means users with billing addresses in South Korea can [create DeepL Pro API and Free API subscriptions](https://www.deepl.com/ko/pro#developer).
* Added support for Portuguese (PT), Russian (RU), and Chinese (ZH) as [glossary](/docs/customize/managing-glossaries) languages, increasing the number of supported glossary language pairs from 28 to 55.
* Added support for JSON-encoded requests for all remaining endpoints (*note that document upload for document translation still requires*`multipart/form-data`).

## Q2 2023

* Added support for user-provided http clients in [PHP client library](https://github.com/DeepL/deepl-php).
* Released an official [DeepL API Postman collection](https://www.postman.com/deepl-api/workspace/deepl-api-developers/overview).
* Added formality support for Japanese (JA) in [text](/api-reference/translate/request-translation) and [document](/api-reference/document/upload-and-translate-a-document) translation.
* Released in-house PDF translation; removed requirement to send data to the US when translating PDF documents ([blog post](https://www.deepl.com/en/blog/deepl-launches-in-house-pdf-translation-for-improved-security-and-efficiency)).

## Q1 2023

* Released an official [DeepL Custom Connector](https://support.deepl.com/hc/en-us/articles/8644041855516-DeepL-API-custom-connector-for-Microsoft-Power-Automate) for Microsoft Power Automate.
* Added support for glossaries in any combination of two languages from the following list: EN (English), DE (German), FR (French), IT (Italian), PL (Polish), NL (Dutch), ES (Spanish, JA (Japanese). This represents an increase from 8 to 28 supported glossary language pairs.
* Added XLIFF as a [document translation](/api-reference/document/upload-and-translate-a-document) format (*note that only documents from version 2.0 are supported, and there is no support for the legacy 1.2 format*).
* Added support for new languages for text and document translation: KO (Korean) and NB (Norwegian Bokmål). [Blog post here](https://www.deepl.com/en/blog/welcome-korean-and-norwegian).

**2022**

## Q4 2022

* Moved [HTML handling](/docs/translate/translating-html) out of beta after fixing the most commonly reported user issues.
* Released an official [Java client library](https://github.com/DeepL/deepl-java).
* Added support for JSON-encoded requests for [text translation](/api-reference/translate/request-translation), [usage](/api-reference/usage-and-quota/check-usage-and-limits), and [languages](/api-reference/languages/retrieve-supported-languages) endpoints.

## Q3 2022

* Released an official [PHP client library](https://github.com/DeepL/deepl-php).
* Added support for a new language for [text](/api-reference/translate/request-translation) and [document](/api-reference/document/upload-and-translate-a-document) translation: UK (Ukrainian). [Blog post here](https://www.deepl.com/en/blog/deepl-learns-ukrainian).

## Before Q3 2022

* Released an official DeepL API [OpenAPI spec](https://github.com/DeepL/openapi).
* Released an official [NodeJS client library](https://github.com/DeepL/deepl-node).
* Released an official [.NET client library](https://github.com/DeepL/deepl-dotnet).
* Released an official [Python client library](https://github.com/DeepL/deepl-python).
* Added support for [glossaries](/docs/customize/managing-glossaries) in the DeepL API.
* Released an open-source sample project for [translating with DeepL in Google Sheets](https://github.com/DeepL/google-sheets-example).
* Added the `prefer_less` and `prefer_more` formality options on [text translation](/api-reference/translate/request-translation), giving more graceful fallback than the strict `more` and `less` values for languages without full formality support.
* Added CSV as an entries format for creating [glossaries](/docs/customize/managing-glossaries), alongside the existing tab-separated format.
* Removed the previous limit of 50 `text` parameters per [text translation](/api-reference/translate/request-translation) request.
* ...and much more :)


# Usage and limits
Source: https://developers.deepl.com/docs/resources/usage-limits

Request size, header, and character limits for the DeepL API, plus the maximum upload size for each document format.

### API Limits

| Type of limit | Maximum limit |
| - | - |
| Header size | 16 KiB (16\*1024 bytes) |
| Total request size | 128 KiB (128\*1024 bytes) |

### Maximum Upload Limits Per Document Format

| File Format | DeepL API - free plans | DeepL API - paid plans |
| - | - | - |
| Word (.docx / .doc) | 10 MB 500,000 characters | 100 MB 1 million characters |
| PowerPoint (.pptx) | 10 MB 500,000 characters | 100 MB 1 million characters |
| Excel (.xlsx) | 10 MB 500,000 characters | 30 MB 1 million characters |
| Excel Macro-Enabled (.xlsm)\*\* | 10 MB 500,000 characters | 30 MB 1 million characters |
| PDF (.pdf) | 10 MB 500,000 characters | 100 MB 1 million characters |
| Text (.txt) | 1 MB 500,000 characters | 1 MB 1 million characters |
| HTML (.html) | 5 MB 500,000 characters | 5 MB 1 million characters |
| IDML (.idml) | 10 MB 500,000 characters | 30 MB 1 million characters |
| MIF (.mif) | 10 MB 500,000 characters | 30 MB 1 million characters |
| XML (.xml) | 10 MB 500,000 characters | 10 MB 1 million characters |
| JSON (.json) | 1 MB 500,000 characters | 1 MB 1 million characters |
| YAML (.yaml / .yml)\*\* | 1 MB 500,000 characters | 1 MB 1 million characters |
| Java Properties (.properties)\*\* | 1 MB 500,000 characters | 1 MB 1 million characters |
| iOS/macOS Strings (.strings)\*\* | 1 MB 500,000 characters | 1 MB 1 million characters |
| Markdown (.md / .markdown)\*\* | 1 MB 500,000 characters | 1 MB 1 million characters |
| DITA (.dita) | 5 MB 500,000 characters | 5 MB 1 million characters |
| XLIFF (.xlf/.xliff)\* | 10 MB 500,000 characters | 10 MB 1 million characters |
| SRT (.srt) | 150 KB 500,000 characters | 150 KB 1 million characters |
| WebVTT (.vtt)\*\* | 150 KB 500,000 characters | 150 KB 1 million characters |
| SCORM (.zip)\*\* | 10 MB 500,000 characters | 10 MB 1 million characters |
| RESX (.resx)\*\* | 1 MB 500,000 characters | 1 MB 1 million characters |
| ODT (.odt)\*\* | 10 MB 500,000 characters | 30 MB 1 million characters |
| RTF (.rtf)\*\* | 10 MB 500,000 characters | 30 MB 1 million characters |
| Images (.jpeg/.png)\*\* | 3 MB 500,000 characters | 3 MB 1 million characters |

\*DeepL supports XLIFF versions 1.2, 2.0, and 2.1 (2.1 shares the 2.0 core namespace).\

\*\*Currently in Beta. During the Beta phase, characters translated in these file formats are not billed and not counted against your character threshold.

### Your Usage

Retrieve usage information within the current billing period together with the corresponding account limits.

Usage is returned and tracked for translated characters. Note that for [text translation](/api-reference/translate/request-translation), characters are still counted toward billing when the source and target languages are equal.

Character usage includes both text and document translations, and is measured by the source text length in Unicode code points. For example, "A", "Δ", "あ", and "深" are each counted as a single character. The `character_count` field returned by the [`/usage` endpoint](/api-reference/usage-and-quota/check-usage-and-limits) is a sum of Translate API and Write API characters.


# Controlling Writing Style and Tone
Source: https://developers.deepl.com/docs/translate/controlling-writing-style-and-tone

Steer Write API output with the writing_style and tone parameters: available values, per-language support, and prefer_ fallback behavior.

The [`/v2/write/rephrase` endpoint](/api-reference/improve-text/request-text-improvement) accepts two parameters that steer how your text is rewritten: `writing_style` changes the register of the text, and `tone` changes how it sounds. A request can include one or the other, but not both.

## Writing styles

| Value | Fallback variant |
| :- | :- |
| `simple` | `prefer_simple` |
| `business` | `prefer_business` |
| `academic` | `prefer_academic` |
| `casual` | `prefer_casual` |
| `default` | (same as omitting `writing_style`) |

## Tones

| Value | Fallback variant |
| :- | :- |
| `enthusiastic` | `prefer_enthusiastic` |
| `friendly` | `prefer_friendly` |
| `confident` | `prefer_confident` |
| `diplomatic` | `prefer_diplomatic` |
| `default` | (same as omitting `tone`) |

## Language support and fallback behavior

Styles and tones are currently supported for the target languages `de`, `en-GB`, `en-US`, `es`, `fr`, `it`, `pt-BR`, and `pt-PT`. To check support dynamically, call [`GET /v3/languages?resource=write`](/docs/languages/using-the-languages-api) and look for the `writing_style` or `tone` feature key on the target language.

The `prefer_` variants fall back to `default` when the target language doesn't support styles or tones; the non-prefixed values return an HTTP 400 error in that case. Use the `prefer_` variants when you don't set a `target_lang` explicitly, since the detected language may not support styles or tones.

## Example

This request rewrites the same text in a diplomatic tone:

```sh Sample request theme={null}
curl -X POST https://api.deepl.com/v2/write/rephrase \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": [
      "Your proposal misses the point entirely."
    ],
    "target_lang": "en-US",
    "tone": "prefer_diplomatic"
}'
```

```json Sample response theme={null}
{
  "improvements": [
    {
      "text": "It seems that your proposal may not fully capture the essence of the issue at hand.",
      "detected_source_language": "en",
      "target_language": "en-US"
    }
  ]
}
```

New to the Write API? Start with the [Write Quickstart](/docs/translate/write-quickstart).


# Translate
Source: https://developers.deepl.com/docs/translate/overview

Translate text strings and complete documents with the DeepL API. Find quickstarts, markup handling guides, and customization options.

The Translate API converts text between any of the [supported languages](/docs/getting-started/supported-languages) through two endpoints:

* **Text translation** (`/v2/translate`): translate one or many strings per request, with automatic source language detection. Suited for UI strings, messages, and any text your application handles directly.
* **Document translation** (`/v2/document`): upload complete files, including Word, PowerPoint, PDF, and HTML, and download the translation with the original formatting intact.

## Start here

> **[Translate Text Quickstart](/docs/translate/translate-text-quickstart)**
>
> Send your first translation request and batch multiple strings into one call.

> **[Translate Documents Quickstart](/docs/translate/translate-documents-quickstart)**
>
> Upload a Word document, poll its status, and download the translated file.

> **[How to Use the Context Parameter](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter)**
>
> Improve translation quality for short or ambiguous text by passing surrounding context.

> **[XML and HTML Handling](/docs/xml-and-html-handling/xml)**
>
> Translate markup without breaking it: tag handling for XML, HTML, and structured content.

> **[API Reference](/api-reference/translate/request-translation)**
>
> Full request and response schemas for the text and document translation endpoints.

## Customize translations

Beyond per-request parameters, DeepL's customization features let you tailor translations to your domain and keep terminology consistent: glossaries, style rules, custom instructions, and translation memories. They all work with both text and document translation; see the [Customize tab](/docs/customize/overview) for guides on each.


# Translate Documents Quickstart
Source: https://developers.deepl.com/docs/translate/translate-documents-quickstart

Upload a Word document to the DeepL API, poll its translation status, and download the translated file, in three curl calls or one client library call.

In this tutorial, you'll translate a complete document with the DeepL API: upload a file, poll until the translation is done, and download the result. By the end, you'll have run the full asynchronous flow with curl and seen how the client libraries collapse it into a single call.

Document translation preserves the file's formatting and supports Word, PowerPoint, Excel, PDF, HTML, XLIFF, SRT subtitles, and more. See the [full list of supported formats](/api-reference/document/upload-and-translate-a-document).

## Prerequisites

* A DeepL API account and your API key from [your account settings](https://www.deepl.com/your-account/keys). New to the API? Start with the [Translate Text Quickstart](/docs/translate/translate-text-quickstart), which covers signup in more detail.
* `curl` installed on your machine
* A document to translate. The examples use a Word file named `order-confirmation.docx`; any supported format works.

> [!TIP]
>
> If you're on a free API plan, replace `https://api.deepl.com` with `https://api-free.deepl.com` in curl examples. Client libraries detect your account type and pick the correct URL automatically.

## Building with an AI coding agent?

Wire it up to the [DeepL Docs MCP Server](/docs/getting-started/docs-mcp-server) so it can search and read this documentation while it writes code. In Claude Code:

```bash theme={null}
claude mcp add --transport http deepl-docs https://developers.deepl.com/mcp
```

Then describe what you want to build. To get the same result as this tutorial, paste:

```text wrap theme={null}
Using the DeepL API, write a script that uploads order-confirmation.docx for translation to German, polls the status until it's done, and downloads the translated file.
```

Setup instructions for Claude Desktop, Cursor, VS Code, and other MCP clients are on the [Docs MCP Server page](/docs/getting-started/docs-mcp-server).

## Step 1: Upload the document

Document translation runs asynchronously, so the flow has three calls: upload the file, check the status, and download the result. Start by uploading the file as `multipart/form-data` with a `target_lang`:

```sh Sample request theme={null}
export API_KEY={YOUR_API_KEY}

curl -X POST https://api.deepl.com/v2/document \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --form 'target_lang=DE' \
  --form 'file=@order-confirmation.docx'
```

```json Sample response theme={null}
{
  "document_id": "04DE5AD98A02647D83285A36021911C6",
  "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"
}
```

The response returns as soon as the upload completes, while the translation continues in the background. Store both values: the `document_id` identifies the translation, and the `document_key` authorizes the status and download calls in the next steps.

As with text translation, the source language is detected automatically, or you can pin it with an optional `source_lang` form field.

## Step 2: Poll the translation status

Check the status by sending the `document_key` to the `/v2/document/{document_id}` endpoint:

```sh Sample request theme={null}
curl -X POST https://api.deepl.com/v2/document/04DE5AD98A02647D83285A36021911C6 \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"
}'
```

While the document is being translated, the `status` field is `queued` or `translating`:

```json Sample response: still translating theme={null}
{
  "document_id": "04DE5AD98A02647D83285A36021911C6",
  "status": "translating",
  "seconds_remaining": 20
}
```

Repeat the call at regular intervals or with exponential backoff until the status is `done`. Small documents typically finish in seconds; larger ones can take a minute or two. Treat `seconds_remaining` as a rough estimate only.

```json Sample response: done theme={null}
{
  "document_id": "04DE5AD98A02647D83285A36021911C6",
  "status": "done",
  "billed_characters": 1337
}
```

A status of `error` comes with a `message` field explaining what went wrong, for example when the source and target language are the same.

## Step 3: Download the translated file

Once the status is `done`, download the result from the `/result` endpoint and save it to a file:

```sh Sample request theme={null}
curl -X POST https://api.deepl.com/v2/document/04DE5AD98A02647D83285A36021911C6/result \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A"
}' \
  --output order-confirmation-de.docx
```

Open `order-confirmation-de.docx` and you'll find the German translation with the original layout intact.

For privacy reasons, the document is removed from DeepL's servers once you download it, so it can't be downloaded twice. To translate the same file again, start over from step 1. Download promptly: leaving too many finished translations unretrieved can cause new upload requests to fail with HTTP 429.

> [!WARNING]
>
> Every submitted `docx`, `doc`, `pptx`, `xlsx`, or `pdf` file is billed a minimum of 50,000 characters, regardless of how much text it contains.

## Or: one call with a client library

The [official client libraries](/docs/getting-started/client-libraries) wrap all three steps, upload, polling, and download, in a single method call:

**Python**

```py Sample request theme={null}
import deepl

auth_key = "{YOUR_API_KEY}"  # replace with your key
deepl_client = deepl.DeepLClient(auth_key)

deepl_client.translate_document_from_filepath(
    "order-confirmation.docx",
    "order-confirmation-de.docx",
    target_lang="DE",
)
```

**JavaScript**

```javascript Sample request theme={null}
import * as deepl from 'deepl-node';

const authKey = "{YOUR_API_KEY}"; // replace with your key
const deeplClient = new deepl.DeepLClient(authKey);

(async () => {
    await deeplClient.translateDocument(
        'order-confirmation.docx',
        'order-confirmation-de.docx',
        null,
        'de'
    );
})();
```

The PHP, C#, Java, and Ruby libraries offer the same convenience method; see each [library's documentation](/docs/getting-started/client-libraries) for details.

## Next steps

You've now run the complete document translation flow. To keep going:

* Read the [document translation guide](/docs/best-practices/document-translations) for format-specific behavior (XML, XLIFF, JSON, IDML) and error handling
* Convert formats on the way through, like PDF in and editable Word out, with the `output_format` parameter in the [`/document` reference](/api-reference/document/upload-and-translate-a-document)
* Enforce your terminology with [glossaries](/docs/customize/glossaries-in-the-real-world)
* Check the [upload size limits per format](/docs/resources/usage-limits#maximum-upload-limits-per-document-format) before going to production


# Translate Text Quickstart
Source: https://developers.deepl.com/docs/translate/translate-text-quickstart

Send your first text translation request to the DeepL API and batch multiple strings into a single call.

In this tutorial, you'll translate your first text with the DeepL API, then batch several strings into a single request. By the end, you'll have made the two most common types of text translation request, using curl or the official client library for your language.

## Prerequisites

* A DeepL API account. Visit [our plans page](https://www.deepl.com/pro-api#api-pricing), choose a plan, and sign up. If you already have a DeepL Translator account, you need to log out and [create a separate account](https://support.deepl.com/hc/articles/360019358999-Change-plan) for the API.
* Your API key, which you can find in [your account settings](https://www.deepl.com/your-account/keys). To learn more about keys, see [Authentication](/docs/getting-started/auth).
* `curl`, or one of the [official client libraries](/docs/getting-started/client-libraries) for Python, JavaScript, PHP, C#, Java, or Ruby.

> [!TIP]
>
> If you're on a free API plan, replace `https://api.deepl.com` with `https://api-free.deepl.com` in curl examples. Client libraries detect your account type and pick the correct URL automatically.

## Building with an AI coding agent?

Wire it up to the [DeepL Docs MCP Server](/docs/getting-started/docs-mcp-server) so it can search and read this documentation while it writes code. In Claude Code:

```bash theme={null}
claude mcp add --transport http deepl-docs https://developers.deepl.com/mcp
```

Then describe what you want to build. To get the same result as this tutorial, paste:

```text wrap theme={null}
Using the DeepL API, write a script that translates a list of English strings to German and prints the results.
```

Setup instructions for Claude Desktop, Cursor, VS Code, and other MCP clients are on the [Docs MCP Server page](/docs/getting-started/docs-mcp-server).

## Step 1: Send your first translation request

A translation request needs only two parameters: `text`, the text to translate, and `target_lang`, the language you're translating to. You don't need to specify the source language. DeepL detects it and returns it in the response as `detected_source_language`. If your text is very short or mixes languages, you can pin the source with the optional `source_lang` parameter.

Language codes follow ISO 639, like `DE` for German or `JA` for Japanese, and are case-insensitive. Some target languages support regional variants, like `en-US` or `pt-BR`. See the full list of [supported languages](/docs/getting-started/supported-languages).

**cURL**

```sh Set the API key theme={null}
export API_KEY={YOUR_API_KEY}
```

```sh Sample request theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": ["Your order has shipped and will arrive on Tuesday."],
    "target_lang": "DE"
}'
```

```json Sample response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Ihre Bestellung wurde versandt und kommt am Dienstag an."
    }
  ]
}
```

**Python**

```sh Install client library theme={null}
pip install deepl
```

```py Sample request theme={null}
import deepl

auth_key = "{YOUR_API_KEY}"  # replace with your key
deepl_client = deepl.DeepLClient(auth_key)

result = deepl_client.translate_text(
    "Your order has shipped and will arrive on Tuesday.",
    target_lang="DE",
)
print(result.text)
```

```text Sample output theme={null}
Ihre Bestellung wurde versandt und kommt am Dienstag an.
```

**JavaScript**

```sh Install client library theme={null}
npm install deepl-node
```

```javascript Sample request theme={null}
import * as deepl from 'deepl-node';

const authKey = "{YOUR_API_KEY}"; // replace with your key
const deeplClient = new deepl.DeepLClient(authKey);

(async () => {
    const result = await deeplClient.translateText(
        'Your order has shipped and will arrive on Tuesday.',
        null,
        'de'
    );
    console.log(result.text);
})();
```

```text Sample output theme={null}
Ihre Bestellung wurde versandt und kommt am Dienstag an.
```

**PHP**

```sh Install client library theme={null}
composer require deeplcom/deepl-php
```

```php Sample request theme={null}
require_once 'vendor/autoload.php';
use DeepL\Client;

$authKey = "{YOUR_API_KEY}"; // replace with your key
$deeplClient = new DeepL\DeepLClient($authKey);

$result = $deeplClient->translateText(
    'Your order has shipped and will arrive on Tuesday.',
    null,
    'de'
);
echo $result->text;
```

```text Sample output theme={null}
Ihre Bestellung wurde versandt und kommt am Dienstag an.
```

**C#**

```sh Install client library theme={null}
dotnet add package DeepL.net
```

```csharp Sample request theme={null}
using DeepL; // this imports the DeepL namespace. Use the code below in your main program.

var authKey = "{YOUR_API_KEY}"; // replace with your key
var client = new DeepLClient(authKey);

var translatedText = await client.TranslateTextAsync(
    "Your order has shipped and will arrive on Tuesday.",
    null,
    LanguageCode.German);
Console.WriteLine(translatedText);
```

```text Sample output theme={null}
Ihre Bestellung wurde versandt und kommt am Dienstag an.
```

**Java**

```java Install client library theme={null}
// For instructions on installing the DeepL Java library,
// see https://github.com/DeepL/deepl-java?tab=readme-ov-file#installation
```

```java Sample request theme={null}
import com.deepl.api.*;

public class Main {
    public static void main(String[] args) throws DeepLException, InterruptedException {
        String authKey = "{YOUR_API_KEY}"; // replace with your key
        DeepLClient client = new DeepLClient(authKey);

        TextResult result = client.translateText(
            "Your order has shipped and will arrive on Tuesday.", null, "de");
        System.out.println(result.getText());
    }
}
```

```text Sample output theme={null}
Ihre Bestellung wurde versandt und kommt am Dienstag an.
```

**Ruby**

```sh Install client library theme={null}
gem install deepl-rb
```

```ruby Sample request theme={null}
require 'deepl'

DeepL.configure do |config|
    config.auth_key = '{YOUR_API_KEY}' # replace with your key
end

translation = DeepL.translate 'Your order has shipped and will arrive on Tuesday.', nil, 'DE'
puts translation.text
```

```text Sample output theme={null}
Ihre Bestellung wurde versandt und kommt am Dienstag an.
```

The examples hardcode the key to keep them short. In production code, store your API key in an environment variable instead.

> [!WARNING]
>
> For security reasons, you can't call the DeepL API directly from client-side JavaScript. During testing or prototyping, route requests through [a simple proxy](/docs/learning-how-tos/cookbook/nodejs-proxy) instead.

## Step 2: Translate multiple strings in one call

The `text` parameter is an array, so one request can carry many strings, like every notification in a template file. Each string is translated separately and the response preserves their order. If you don't set `source_lang`, DeepL detects the language of each string individually.

```sh Sample request theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": [
      "Your order has shipped.",
      "Estimated delivery: Tuesday, July 14."
    ],
    "target_lang": "DE"
}'
```

```json Sample response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Ihre Bestellung wurde versandt."
    },
    {
      "detected_source_language": "EN",
      "text": "Voraussichtliche Lieferung: Dienstag, 14. Juli."
    }
  ]
}
```

The client libraries accept a list of strings in the same `translate_text` methods you used in step 1.

The total request body is limited to 128 KiB. For anything larger, or for files whose formatting should be preserved, translate a document instead.

## Next steps

You've now covered the core text translation workflow: single strings and batches. To keep going:

* Translate entire files, formatting included, with the [Translate Documents Quickstart](/docs/translate/translate-documents-quickstart)
* Try requests with more parameters in [our playground](https://developers.deepl.com/api-reference/translate/request-translation?playground=open) or [Postman](/docs/getting-started/test-your-api-requests-with-postman)
* Improve translation quality for short or ambiguous text with the [context parameter](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter)
* Choose between speed- and quality-optimized models with the `model_type` parameter, documented in the [`/translate` reference](/api-reference/translate/request-translation)
* Translate into regional variants like `pt-BR` with the [language variants guide](/docs/learning-how-tos/examples-and-guides/translating-between-variants)
* Enforce your terminology with [glossaries](/docs/customize/glossaries-in-the-real-world)
* Check [usage and limits](/docs/resources/usage-limits) before going to production


# Translating HTML
Source: https://developers.deepl.com/docs/translate/translating-html

Learn how to translate HTML content with the DeepL API and exclude specific elements from translation.

To translate HTML content, set the `tag_handling` parameter to `html`. The API extracts the text from the HTML structure, translates it, and places the translation back into the structure. Without `tag_handling`, tags are treated as regular text.

Set `tag_handling_version` to `v2` to use the improved tag handling algorithm. HTML input is never strictly parsed, so invalid HTML doesn't cause errors in either version. For version details and defaults, see the [`tag_handling_version` parameter](/api-reference/translate/request-translation).

```bash Example request theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": ["<p>This is a <strong>premium</strong> feature.</p>"],
    "target_lang": "DE",
    "tag_handling": "html",
    "tag_handling_version": "v2"
}'
```

```json Example response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "<p>Dies ist eine <strong>Premium</strong>-Funktion.</p>",
      "tag_handling_version": "v2"
    }
  ]
}
```

You don't need to set `split_sentences` for HTML: with `tag_handling=html` it defaults to `nonewlines`, which splits sentences on punctuation only and gives the best translation quality for HTML. To also split sentences on newlines, set `split_sentences=1`.

To translate non-HTML XML content, see [Translating XML](/docs/translate/translating-xml).

## Exclude elements from translation

To exclude an element from translation, add the `translate="no"` or `class="notranslate"` attribute to it. In the following example, `translate="no"` prevents translation of the paragraph:

> **Disable translation of elements example**
>
> ```markup Example request theme={null}
> <!DOCTYPE html>
> <html>
>   <body>
>     <h1>My First Heading</h1>
>     <p translate="no">My first paragraph.</p>
>   </body>
> </html>
> ```
>
> ```markup Example response theme={null}
> <!DOCTYPE html>
> <html>
>   <body>
>     <h1>Meine erste Überschrift</h1>
>     <p translate="no">My first paragraph.</p>
>   </body>
> </html>
> ```


# Translating Large Volumes of Text
Source: https://developers.deepl.com/docs/translate/translating-large-volumes

Batch texts, control sentence splitting, and parallelize requests to translate high volumes efficiently with the text translation endpoint.

The [`/v2/translate` endpoint](/api-reference/translate/request-translation) accepts up to 50 texts per request and request bodies up to 128 KiB. This guide shows how to make the most of each request when you have a lot of text to translate: sending whole paragraphs, batching texts, running requests in parallel, and protecting content that shouldn't be translated.

## Send whole paragraphs as one text

If your text is contiguous, submit entire paragraphs in a single `text` value. Before translating, the engine splits the text into sentences, normally on punctuation marks and newlines, and returns the whole translated paragraph. Don't assume every period acts as a sentence separator; the engine handles abbreviations and similar cases.

```sh Example request theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": ["The table is green. The chair is black."],
    "target_lang": "DE"
}'
```

```json Example response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Der Tisch ist grün. Der Stuhl ist schwarz."
    }
  ]
}
```

## Control sentence splitting

Automatic splitting can occasionally divide what is really a single sentence, especially in text with uncommon character sequences that contain punctuation. The `split_sentences` parameter controls this behavior:

| Value | Behavior |
| :- | :- |
| `1` | Split on punctuation and newlines (default) |
| `nonewlines` | Split on punctuation only (default when `tag_handling=html`) |
| `0` | No splitting; the whole input is treated as one sentence |

If your application already sends exactly one sentence per `text` value, set `split_sentences` to `0` to prevent unintended splits. With splitting disabled, overlong inputs are cut off rather than translated, so split long text into sentences yourself before submitting.

Newlines split sentences under the default setting. If your text contains line breaks mid-sentence, either clean them up before sending or use `split_sentences=nonewlines`.

## Batch up to 50 texts per request

The `text` array can carry up to 50 entries per request. Translations come back in the same order:

```sh Example request theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": [
      "This is the first sentence.",
      "This is the second sentence.",
      "This is the third sentence."
    ],
    "target_lang": "DE"
}'
```

```json Example response theme={null}
{
  "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."
    }
  ]
}
```

> [!WARNING]
>
> Each text in the array is translated independently; texts don't share context with each other. If one text would help translate another, like a headline and its article body, combine them into one text or pass the shared information through the [`context` parameter](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter), which applies to every text in the request.

## Run requests in parallel

For volumes beyond what batching covers, send multiple requests concurrently from several threads or processes. Watch for HTTP 429 responses and back off accordingly; see [error handling best practices](/docs/best-practices/error-handling) for retry strategies.

## Protect embedded markers

Uncommon character sequences that act as markers in your system, like placeholders or template syntax, might get translated or removed, corrupting your structure. Either split your text so markers don't need to be sent, or convert markers to XML tags and enable [XML handling](/docs/translate/translating-xml) or [HTML handling](/docs/translate/translating-html).

## When to switch to document translation

The total request body is limited to 128 KiB, and a `text` array is capped at 50 entries. For complete files, or text that exceeds these limits, use [document translation](/docs/translate/translate-documents-quickstart) instead: upload limits are far higher and formatting is preserved. See [usage and limits](/docs/resources/usage-limits) for the exact caps per plan.


# Translating XML
Source: https://developers.deepl.com/docs/translate/translating-xml

Learn how to translate XML content with the DeepL API while preserving its structure, and how to control sentence splitting.

To translate XML content, set the `tag_handling` parameter to `xml`. The API extracts the text from the XML structure, translates it, and places the translation back into the structure. Without `tag_handling`, tags are treated as regular text.

Set `tag_handling_version` to `v2` to use the improved tag handling algorithm. For version details and defaults, see the [`tag_handling_version` parameter](/api-reference/translate/request-translation).

```bash Example request theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": ["Press <b>Continue</b> to advance."],
    "target_lang": "DE",
    "tag_handling": "xml",
    "tag_handling_version": "v2"
}'
```

```json Example response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Drücken Sie <b>„Weiter\",</b> um fortzufahren.",
      "tag_handling_version": "v2"
    }
  ]
}
```

> [!NOTE]
>
> Accounts that first used tag handling after December 1, 2025 default to v2. All other accounts default to v1 and need to set `tag_handling_version=v2` explicitly. Results differ between versions, so test representative content before switching versions in production.

> [!WARNING]
>
> With v2, XML input is strictly parsed: invalid XML (for example, an unclosed tag) returns the error `Tag handling parsing failed, please check input.` Make sure your XML is well-formed and handle this error in your integration.

To translate HTML content, see [Translating HTML](/docs/translate/translating-html).

## Translate sentences with inline markup

Send marked-up text as is; tags stay attached to the words they wrap, and placeholder tags are placed next to the translation of the words that precede or follow them:

**Basic Example**

```markup Request theme={null}
Press <i>Continue</i> to advance to the next page.
```

```markup Response theme={null}
Drücken Sie <i>Weiter</i>, um zur nächsten Seite zu gelangen.
```

**With Attributes**

```markup Request theme={null}
<x id="17">Please welcome the participants</x> to today's meeting.
```

```markup Response theme={null}
<x id="17">Bitte begrüßen Sie die Teilnehmer</x> des heutigen Treffens.
```

**Nested Tags**

```markup Request theme={null}
The firm said it had been conducting an <a>internal <b>investigation</b></a> for several months.
```

```markup Response theme={null}
Das Unternehmen sagte, dass es seit mehreren Monaten eine <a>interne <b>Untersuchung</b></a>durchgeführt habe.
```

**Placeholder Tag**

```markup Request theme={null}
Artificial intelligence<a/> is already shaping our everyday<b></b> lives.
```

```markup Response theme={null}
Künstliche Intelligenz<a/> prägt bereits heute unseren Alltag<b></b>.
```

## Exclude content from translation

List tags whose content should not be translated in the `ignore_tags` parameter. The example below uses `ignore_tags=x` to preserve the text between `<x>` and `</x>` as is:

> **Example: ignore \\\<x\\> tag**
>
> ```text Parameters theme={null}
> tag_handling=xml, ignore_tags=x
> ```
>
> ```markup Request theme={null}
> Please open the page <x>Settings</x> to configure your system.
> ```
>
> ```markup Response theme={null}
> Bitte öffnen Sie die Seite <x>Settings</x> um Ihr System zu konfigurieren.
> ```

## Translate whole XML documents

Send complete XML files the same way, with `split_sentences=nonewlines` so that line breaks in the file don't split sentences. Tags that contain text (here `title` and `par`) are treated as sentence boundaries, and the content of each is translated separately:

> **Example**
>
> ```text Parameters theme={null}
> tag_handling=xml, split_sentences=nonewlines
> ```
>
> ```markup Example request theme={null}
> <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>
> ```
>
> ```markup Example response theme={null}
> <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>
> ```

Without `split_sentences=nonewlines`, a newline in the middle of a sentence causes each part to be translated separately, producing wrong results:

> **Incorrect translation due to new lines**
>
> ```markup Request theme={null}
> <div>She bought oat
> biscuits.</div>
> ```
>
> ```markup Response theme={null}
> <div>Sie kaufte Hafer
> Kekse.</div>
> ```
>
> The two parts of the sentence have been translated separately: "oat biscuits" became "Hafer Kekse" instead of "Haferkekse".

## Keep sentences together across tags

When a single sentence is spread across multiple text-bearing tags, list those tags in the `non_splitting_tags` parameter so the sentence is translated as a whole:

**Restricted Splitting**

```text Parameters theme={null}
tag_handling=xml, non_splitting_tags=par
```

```markup Request theme={null}
<par>The firm said it had been </par><par> conducting an internal investigation.</par>
```

```markup Response theme={null}
<par>Die Firma sagte, dass sie</par><par> eine interne Untersuchung durchgeführt</par><par> habe</par><par>.</par>
```

The sentence is translated as a whole and the `par` tags are treated as markup. Because the translation of "had been" moved to another position in the German sentence, the tags are duplicated (which is expected here).

**Without non\_splitting\_tags**

```text Parameters theme={null}
tag_handling=xml
```

```markup Request theme={null}
<par>The firm said it had been </par><par> conducting an internal investigation.</par>
```

```markup Response theme={null}
<par>Die Firma sagte, es sei eine gute Idee gewesen.</par><par> Durchführung einer internen Untersuchung.</par>
```

Each `par` element is translated separately, producing an incorrect translation.

## Control sentence splitting manually

If automatic detection of the XML structure doesn't yield good results for your files, turn it off with `outline_detection=0` and list your structure tags in the `splitting_tags` parameter. The example below reproduces the automatic behavior for the document shown earlier:

> **Outline detection example**
>
> ```text Parameters theme={null}
> tag_handling=xml, split_sentences=nonewlines, outline_detection=0, splitting_tags=par,title
> ```
>
> ```markup Example request theme={null}
> <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>
> ```
>
> ```markup Example response theme={null}
> <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>
> ```

This approach takes more setup but gives you full control over how the translation output is structured.


# Understanding Model Types
Source: https://developers.deepl.com/docs/translate/understanding-model-types

How the model_type parameter chooses between latency-optimized and quality-optimized translation models, and how DeepL selects the model for each request.

DeepL hosts many AI models for translation and deploys new ones continuously. Rather than asking you to pick a specific model, and update your integration every time models change, the `model_type` parameter of the [`/v2/translate` endpoint](/api-reference/translate/request-translation) lets you state your goal: the lowest possible latency or the highest possible translation quality. DeepL then chooses the most suitable model for your language pair and request.

## Parameter values

The `model_type` parameter accepts three values:

| Value | Behavior |
| :- | :- |
| `latency_optimized` | Aims to serve the request as fast as possible (default when `model_type` is omitted) |
| `quality_optimized` | Aims for the highest translation quality |
| `prefer_quality_optimized` | Legacy value, currently identical to `quality_optimized` |

All features and language pairs are compatible with all `model_type` values. As of December 2025, all source and target languages are supported by next-gen models.

When you set `model_type`, the response includes a `model_type_used` field indicating which kind of model served the request:

```sh Example request theme={null}
curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": ["Your order has shipped and will arrive on Tuesday."],
    "target_lang": "DE",
    "model_type": "quality_optimized"
}'
```

```json Example response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Ihre Bestellung wurde versandt und kommt am Dienstag an.",
      "model_type_used": "quality_optimized"
    }
  ]
}
```

## How DeepL selects the model

The parameter expresses a goal, not a model name. DeepL fulfills it on a best-effort basis: for some language pairs and requests, only one model can be used, and not every pair behaves differently between the two values. DeepL may also change which model serves a given `model_type` when the change is a net benefit, for example a quality increase with no significant latency cost, or a large latency reduction with at most a very slight quality trade-off.

This means you never need to update your code for new model releases or track model names: the API keeps choosing the best available model for your stated goal.

## Notes

* `model_type` applies to text translation only. The [`/v2/document` endpoint](/api-reference/document/upload-and-translate-a-document) accepts the parameter without error but ignores it.
* The [`/v3/languages` endpoint](/docs/languages/using-the-languages-api) doesn't yet report `model_type` support per language. This information will be added in a future update.


# Write Quickstart
Source: https://developers.deepl.com/docs/translate/write-quickstart

Improve your first text with the DeepL Write API: rephrase for clarity, apply corrections-only mode, and change the writing style.

In this tutorial, you'll improve text with DeepL API for Write: rephrase a text for clarity, run a corrections-only pass that keeps the author's voice intact, and change the writing style. By the end, you'll have used both Write endpoints and know when to pick which.

Unlike translation, Write improves text **within** a language: the source text and `target_lang` must be the same language (improving and translating in one request is not yet supported).

## Prerequisites

* A DeepL API Pro subscription. Write is not yet available on API Free plans, and its use is covered by [these additions to the Service Specification](/api-reference/improve-text/deepl-write-api-service-specification-updates).
* Your API key from [your account settings](https://www.deepl.com/your-account/keys). The same keys work for all DeepL API endpoints, Write included.
* `curl`, or one of the [official client libraries](/docs/getting-started/client-libraries), which support all Write features.

## Building with an AI coding agent?

Wire it up to the [DeepL Docs MCP Server](/docs/getting-started/docs-mcp-server) so it can search and read this documentation while it writes code. In Claude Code:

```bash theme={null}
claude mcp add --transport http deepl-docs https://developers.deepl.com/mcp
```

Then describe what you want to build. To get the same result as this tutorial, paste:

```text wrap theme={null}
Using the DeepL Write API, write a script that rephrases an English text, then runs the same text through corrections-only mode, and prints both results.
```

Setup instructions for Claude Desktop, Cursor, VS Code, and other MCP clients are on the [Docs MCP Server page](/docs/getting-started/docs-mcp-server).

## Step 1: Rephrase a text

The [`/v2/write/rephrase` endpoint](/api-reference/improve-text/request-text-improvement) is Write's broad improvement mode: it fixes spelling and grammar, and may also rewrite sentences for clarity, style, or tone.

```sh Sample request theme={null}
export API_KEY={YOUR_API_KEY}

curl -X POST https://api.deepl.com/v2/write/rephrase \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": [
      "I could relly use sum help with edits on thiss text !"
    ],
    "target_lang": "en-US"
}'
```

```json Sample response theme={null}
{
  "improvements": [
    {
      "text": "I could really use some help editing this text!",
      "detected_source_language": "en",
      "target_language": "en-US"
    }
  ]
}
```

The `text` parameter is an array, so you can improve multiple texts in one request; improvements come back in the same order. The total request body is limited to 10 KiB, so split larger workloads across multiple calls.

`target_lang` currently supports `de`, `en-GB`, `en-US`, `es`, `fr`, `it`, `ja`, `ko`, `pt-BR`, `pt-PT`, and `zh`/`zh-Hans`. To check programmatically, call [`GET /v3/languages?resource=write`](/docs/languages/using-the-languages-api).

> [!TIP]
>
> You can convert between variants of the same language: sending American English text with `target_lang` set to `en-GB` improves the text and converts it to British English.

## Step 2: Fix errors only, keeping the author's voice

When you want corrections without rewrites, use the [`/v2/write/correct` endpoint](/api-reference/improve-text/correct-text) instead. It fixes spelling and grammar with minimal changes to wording, matching the "Corrections Only" mode in the DeepL Translator UI.

```sh Sample request theme={null}
curl -X POST https://api.deepl.com/v2/write/correct \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": [
      "I could relly use sum help with edits on thiss text !"
    ],
    "target_lang": "en-US"
}'
```

```json Sample response theme={null}
{
  "improvements": [
    {
      "text": "I could really use some help with edits on this text!",
      "detected_source_language": "en",
      "target_language": "en-US"
    }
  ]
}
```

Compare the two results: `/write/correct` fixed the errors but kept the original phrasing ("edits on this text"), while `/write/rephrase` also reworded the sentence.

## Step 3: Change the writing style

On `/write/rephrase`, the `writing_style` parameter steers how the text is rewritten:

```sh Sample request theme={null}
curl -X POST https://api.deepl.com/v2/write/rephrase \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": [
      "I could relly use sum help with edits on thiss text !"
    ],
    "target_lang": "en-US",
    "writing_style": "business"
}'
```

```json Sample response theme={null}
{
  "improvements": [
    {
      "text": "I would appreciate some assistance with editing this text.",
      "detected_source_language": "en",
      "target_language": "en-US"
    }
  ]
}
```

Alternatively, the `tone` parameter adjusts how the text sounds (friendly, confident, diplomatic, and more). A request can include `writing_style` or `tone`, but not both. For all available values, per-language support, and the `prefer_` fallback behavior, see [Controlling Writing Style and Tone](/docs/translate/controlling-writing-style-and-tone).

## Next steps

You've now used both Write endpoints and steered the output style. To keep going:

* Explore all style and tone options in [Controlling Writing Style and Tone](/docs/translate/controlling-writing-style-and-tone)
* See the full request and response schemas in the [`/write/rephrase`](/api-reference/improve-text/request-text-improvement) and [`/write/correct`](/api-reference/improve-text/correct-text) references
* Rephrase between language variants with the [language variants guide](/docs/learning-how-tos/examples-and-guides/translating-between-variants)
* Note that Write characters count toward the same [usage quota and cost control limits](/docs/resources/usage-limits) as translation characters


# Message Encoding
Source: https://developers.deepl.com/docs/voice/message-encoding

Choose between JSON and MessagePack encoding for DeepL Voice API WebSocket messages, and avoid the frame type and map encoding pitfalls.

WebSocket messages in a Voice API session can be encoded in two formats, chosen with the `message_format` option when you [request the session](/api-reference/voice/request-session). Start with JSON for the best developer experience, and switch to MessagePack if you need better performance.

| **Format** | **Frame type** | **Binary data** | **Trade-off** |
| :- | :- | :- | :- |
| JSON (default) | TEXT | base64-encoded strings | Human-readable, easy to debug |
| [MessagePack](https://msgpack.org/) | BINARY | raw binary | Roughly 25-30% less bandwidth, 2x-4x faster encoding/decoding |

> [!WARNING]
>
> Send JSON messages as TEXT frames and MessagePack messages as BINARY frames. Sending the wrong frame type results in connection errors.

MessagePack messages must be encoded as maps with string keys, not as arrays. The structure must match the JSON schema exactly, with all field names preserved (for example, `{"source_media_chunk": {"data": <binary>}}`). Some MessagePack libraries default to array encoding for performance, so check your library's configuration.

The following example sends the same audio chunk in both encodings:

```javascript JSON theme={null}
// Raw binary audio data
const audioData = getAudioChunk();

// Base64 encode the audio data
const base64Audio = btoa(audioData);

const message = {
  source_media_chunk: {
    data: base64Audio
  }
};

// Send as TEXT frame
websocket.send(JSON.stringify(message));
```

```javascript MessagePack theme={null}
import { pack } from 'msgpackr';

// Raw binary audio data
const audioData = getAudioChunk();

const message = {
  source_media_chunk: {
    data: audioData  // No base64 encoding needed
  }
};

// Send as BINARY frame
websocket.send(pack(message));
```

For the full list of message types exchanged during a session, see the [WebSocket Streaming reference](/api-reference/voice/websocket-streaming). For how those messages fit into the session lifecycle, see [Understanding Voice Sessions](/docs/voice/understanding-voice-sessions).


# DeepL Voice API
Source: https://developers.deepl.com/docs/voice/overview

Transcribe and translate spoken audio in real time with the DeepL Voice API. Find the streaming guide, core concepts, and language and format reference.

The DeepL Voice API transcribes and translates spoken audio in real time over a WebSocket connection. Within a single streaming session, you can:

* Send one audio stream
* Receive transcripts in the source language
* Receive translations in multiple target languages
* Receive translated speech

> [!NOTE]
>
> **Speech-to-text** (real-time transcription and text translation) and **speech-to-speech** (translated TTS output) are available to all customers with a paid DeepL API subscription.
>
> The provisions applying to DeepL API Enterprise subscriptions also apply to Voice API speech-to-text, with [additions to the Terms and Conditions, Service Specification, and Data Processing Agreement](/api-reference/voice/deepl-voice-api-service-specification-updates) (new sub-processors have been added to serve specific languages).

## Start here

> **[Real-Time Voice Quickstart](/docs/voice/real-time-voice-quickstart)**
>
> Create a session, stream audio over WebSocket, and handle reconnections, with a complete Python example.

> **[Understanding Voice Sessions](/docs/voice/understanding-voice-sessions)**
>
> Understand the session flow, token lifecycle, and how audio and results are delivered.

> **[Message Encoding](/docs/voice/message-encoding)**
>
> Choose between JSON and MessagePack for WebSocket messages.

> **[Supported Voice Languages](/docs/voice/supported-voice-languages)**
>
> Check transcription, translation, and translated speech availability per language.

> **[Voice API Requirements](/docs/voice/voice-api-requirements)**
>
> Check supported audio codecs and containers, chunk sizes, and session limits.

> **[API reference](/api-reference/voice/request-session)**
>
> Full request, message, and response schemas for the Voice API endpoints.

## Customization

Two optional features let you tailor transcription and translation to your domain:

* **Spoken terms**: improve transcription of frequently used terms such as company-specific terminology, acronyms, product names, and team member names. Manage them in [DeepL Home](https://www.deepl.com/en/voice/spoken-terms) or via the API; see [Improving Transcription with Spoken Terms](/docs/customize/improving-transcription-with-spoken-terms).
* **Glossaries**: enforce specific translations for terms in the target language. A session can apply several glossaries in priority order; see [Glossaries in realtime Voice](#glossaries-in-realtime-voice) below and the [Request Session reference](/api-reference/voice/request-session). Manage glossaries in [DeepL Home](https://www.deepl.com/en/glossary) or programmatically with the [Glossaries API](/docs/customize/managing-glossaries).

### Glossaries in realtime Voice

Because Voice translates in real time, glossary terms are matched against the source transcription as it's produced, not against a complete text as in batch text translation. The transcription arrives incrementally, so a glossary term is applied only when its full source term appears in the streamed transcription.

This matters most for multi-word glossary terms. Since the source is transcribed piece by piece, a multi-word term is matched only when its words are transcribed together. In most cases they are, and the term is applied, but a term whose words are concluded across separate transcription segments can occasionally be missed, and the longer the term, the higher that chance. Single-word terms aren't affected in the same way. This is inherent to streaming transcription, not a temporary limitation.

For languages written without spaces between words, such as Japanese, Chinese, and Thai, the transcription also determines where each term begins and ends, so a glossary's source term must correspond to what the transcription produces.

Each glossary must contain a dictionary for the session's source and target language pair. If the source language is detected rather than fixed, and it resolves to a language a glossary has no dictionary for, that glossary isn't applied.

## Code examples

A reference implementation in Python is available in the [DeepL Python library repository](https://github.com/DeepL/deepl-python/tree/main/examples/voice/cli). The official DeepL SDKs don't integrate the Voice API yet, but you can use any WebSocket client library to interact with it.


# Real-Time Voice Quickstart
Source: https://developers.deepl.com/docs/voice/real-time-voice-quickstart

Stream microphone audio to the DeepL Voice API from Python and print live translations to your terminal as the speaker talks.

In this tutorial you'll run a small Python program that captures audio from your microphone, streams it to the DeepL Voice API, and prints the transcript plus German and French translations to your terminal, sentence by sentence, while you speak. You can then extend it to [play the German translation aloud](#hear-the-translation-spoken). The same pattern works for any live audio source: a meeting bot, a phone bridge, or a broadcast feed.

## Prerequisites

* A DeepL API account with Voice API access
* Python 3.10 or later
* Headphones, if you want to [hear the translation spoken](#hear-the-translation-spoken)
* A microphone (no microphone? see [Simulate a live stream from a file](#simulate-a-live-stream-from-a-file))

## Building with an AI coding agent?

Wire it up to the [DeepL Docs MCP Server](/docs/getting-started/docs-mcp-server) so it can search and read this documentation while it writes code. In Claude Code:

```bash theme={null}
claude mcp add --transport http deepl-docs https://developers.deepl.com/mcp
```

Then describe what you want to build. To get the same result as this tutorial, paste:

```text wrap theme={null}
Write a script to stream my microphone to the DeepL Voice API and print the transcript and translations as each sentence concludes.
```

Setup instructions for Claude Desktop, Cursor, VS Code, and other MCP clients are on the [Docs MCP Server page](/docs/getting-started/docs-mcp-server).

## Run the complete example

Install the dependencies:

```bash theme={null}
pip install requests sounddevice websockets
```

Then save this as `live_translation.py` and replace `YOUR_AUTH_KEY` with your DeepL API key:

```python live_translation.py [expandable] theme={null}
import asyncio
import base64
import json
import signal

import requests
import sounddevice
import websockets

AUTH_KEY = "YOUR_AUTH_KEY"
SESSION_ENDPOINT = "https://api.deepl.com/v3/voice/realtime"
TARGET_LANGUAGES = ["de", "fr"]
SAMPLE_RATE = 16000  # Must match the rate declared in source_media_content_type
CHUNK_FRAMES = 3200  # 200 ms per chunk at 16 kHz
RECORD_SECONDS = 30  # Safety cap; Ctrl+C stops recording earlier


def create_session() -> dict:
    response = requests.post(
        SESSION_ENDPOINT,
        headers={"Authorization": f"DeepL-Auth-Key {AUTH_KEY}"},
        json={
            "source_media_content_type": "audio/pcm;encoding=s16le;rate=16000",
            "target_languages": TARGET_LANGUAGES,
        },
    )
    response.raise_for_status()
    return response.json()


async def send_microphone_audio(ws, stop: asyncio.Event) -> None:
    stream = sounddevice.RawInputStream(
        samplerate=SAMPLE_RATE, channels=1, dtype="int16"
    )
    stream.start()
    try:
        for _ in range(RECORD_SECONDS * SAMPLE_RATE // CHUNK_FRAMES):
            if stop.is_set():
                break
            # Read in a worker thread so receiving continues while we block
            data, _overflowed = await asyncio.to_thread(stream.read, CHUNK_FRAMES)
            encoded = base64.b64encode(bytes(data)).decode("ascii")
            await ws.send(json.dumps({"source_media_chunk": {"data": encoded}}))
    finally:
        stream.stop()
        stream.close()
    print("Finalizing transcripts...")
    await ws.send(json.dumps({"end_of_source_media": {}}))


async def receive_results(ws) -> None:
    pending = {}  # Concluded text per language, buffered until a sentence ends

    def handle_update(label: str, segments: list) -> None:
        text = pending.get(label, "") + "".join(s["text"] for s in segments)
        if text.rstrip().endswith((".", "!", "?")):
            print(f"[{label}] {text.strip()}")
            text = ""
        pending[label] = text

    async for message in ws:
        data = json.loads(message)
        if "source_transcript_update" in data:
            handle_update("source", data["source_transcript_update"]["concluded"])
        elif "target_transcript_update" in data:
            update = data["target_transcript_update"]
            handle_update(update["language"], update["concluded"])
        elif "end_of_stream" in data:
            # The very last message: flush any unfinished sentences and exit
            for label, text in pending.items():
                if text.strip():
                    print(f"[{label}] {text.strip()}")
            return
        elif "error" in data:
            raise RuntimeError(f"Voice API error: {data['error']['error_message']}")


async def main() -> None:
    stop = asyncio.Event()
    try:
        asyncio.get_running_loop().add_signal_handler(signal.SIGINT, stop.set)
    except NotImplementedError:
        pass  # Windows: Ctrl+C raises KeyboardInterrupt instead

    session = create_session()
    url = f"{session['streaming_url']}?token={session['token']}"
    async with websockets.connect(url) as ws:
        print("Connected. Speak now (Ctrl+C to stop)...")
        await asyncio.gather(send_microphone_audio(ws, stop), receive_results(ws))
    print("Done. All transcripts are final.")


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass
```

Run it and speak in any [supported source language](/docs/voice/supported-voice-languages). Each sentence prints once it's final, first the transcript, then each translation. Press Ctrl+C when you're done: the script stops recording, waits for the remaining results, and exits cleanly.

```text theme={null}
❯ python live_translation.py
Connected. Speak now (Ctrl+C to stop)...
[source] Hello everyone, welcome to today's demo.
[de] Hallo zusammen, willkommen zur heutigen Demo.
[fr] Bonjour à tous, bienvenue à la démonstration d'aujourd'hui.
^CFinalizing transcripts...
[source] We are testing real-time voice translation.
[de] Wir testen die Sprachübersetzung in Echtzeit.
[fr] Nous testons la traduction vocale en temps réel.
Done. All transcripts are final.
```

## How it works

The program does three things: it creates a session over HTTPS, streams audio to the WebSocket URL it gets back, and handles result messages until the server confirms everything is final.

### The session request

`create_session` sends a POST request with the audio format and target languages. The only required field is `source_media_content_type`; for raw microphone audio, that's PCM at 16 kHz. The response contains the WebSocket URL and a one-time token, and the program connects to `{streaming_url}?token={token}`:

```json theme={null}
{
  "session_id": "4f911080-cfe2-41d4-8269-0e6ec15a0354",
  "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect",
  "token": "VGhpcyBpcyBhIGZha2UgdG9rZW4K"
}
```

If you know the speaker's language in advance, add `"source_language": "en"` and `"source_language_mode": "fixed"` to the request body. This skips language detection and reduces latency. Without them, the language is detected automatically. See the [Request Session reference](/api-reference/voice/request-session) for all parameters, including glossary and formality options.

### Sending audio

`send_microphone_audio` sends each 200-millisecond microphone chunk as a JSON text message with the raw audio base64-encoded:

```json theme={null}
{"source_media_chunk": {"data": "<base64-encoded audio>"}}
```

Keep chunks between 50 and 250 milliseconds for the best latency. When the audio ends (Ctrl+C or the safety cap), the function sends one final message that tells the API to finalize all pending results:

```json theme={null}
{"end_of_source_media": {}}
```

### Receiving transcripts and translations

While audio is being sent, the server pushes `source_transcript_update` and `target_transcript_update` messages on the same connection:

```json theme={null}
{
  "target_transcript_update": {
    "language": "de",
    "concluded": [
      {"text": " Hallo zusammen,", "start_time": 0, "end_time": 1500}
    ],
    "tentative": [
      {"text": " willkommen zur heutigen Demo", "start_time": 1500, "end_time": 2000}
    ]
  }
}
```

**Concluded** segments are final and sent only once; **tentative** segments are provisional and refined by later updates. `receive_results` appends concluded text to a per-language buffer and prints the buffer whenever a sentence completes, which keeps the terminal readable. A UI would also render the tentative text as a live preview that updates in place; see [Understanding Voice Sessions](/docs/voice/understanding-voice-sessions) for this delivery model.

After `end_of_source_media`, the server sends the remaining updates, then `end_of_stream` as the very last message, at which point it's safe to close the connection. See the [WebSocket Streaming reference](/api-reference/voice/websocket-streaming) for the full message schema.

### Reconnecting after a drop

Networks drop, and the Voice API lets you resume a session instead of starting over. If the WebSocket closes unexpectedly, exchange your token for a fresh streaming URL and token, then reconnect. Session state, including configuration and translation context, is preserved.

```python theme={null}
def reconnect(token: str) -> dict:
    response = requests.get(
        SESSION_ENDPOINT,
        headers={"Authorization": f"DeepL-Auth-Key {AUTH_KEY}"},
        params={"token": token},
    )
    response.raise_for_status()
    return response.json()
```

The response has the same shape as the session response above. Always pass the token from your most recent session or reconnection response: each token is single-use, and presenting an outdated one invalidates the session (a 400-level error). In that case, create a new session with `create_session()`.

To add this to the example, wrap the `websockets.connect` block in a `try`/`except websockets.exceptions.ConnectionClosed` loop that calls `reconnect()` and connects again with the new URL and token.

## Hear the translation spoken

The Voice API can also speak the translation aloud, so listeners hear the German version while you talk. In this step you extend `live_translation.py` to request translated speech and play it through your headphones.

> [!WARNING]
>
> Use headphones. If the translated speech plays through your speakers, the microphone picks it up and sends it back for translation.

### Request translated speech

Two session fields turn on translated speech. `target_media_languages` names the language to speak, and the server then streams synthesized audio of each German translation alongside the text. `target_media_content_type` sets the audio format: raw 24 kHz PCM plays directly through `sounddevice`, with no decoder. Add a constant for that playback rate next to `SAMPLE_RATE`:

```python theme={null}
OUTPUT_SAMPLE_RATE = 24000  # Must match the rate declared in target_media_content_type
```

Then add both fields to the request body in `create_session`:

```python theme={null}
json={
    "source_media_content_type": "audio/pcm;encoding=s16le;rate=16000",
    "target_languages": TARGET_LANGUAGES,
    "target_media_languages": ["de"],
    "target_media_content_type": "audio/pcm;encoding=s16le;rate=24000",
},
```

A session synthesizes speech for one language, which also appears in the text translations. To pick a voice or another audio format, see the [Request Session reference](/api-reference/voice/request-session).

### Play the audio as it arrives

Add a player task that writes audio from a queue to your headphones. Like the microphone reader, it blocks in a worker thread so the receive loop keeps running:

```python theme={null}
async def play_translated_speech(audio: asyncio.Queue) -> None:
    stream = sounddevice.RawOutputStream(
        samplerate=OUTPUT_SAMPLE_RATE, channels=1, dtype="int16"
    )
    stream.start()
    try:
        while (pcm := await audio.get()) is not None:
            await asyncio.to_thread(stream.write, pcm)
    finally:
        stream.stop()
        stream.close()
```

Translated speech arrives in `target_media_chunk` messages, each with a `data` array of base64-encoded audio packets. Replace `receive_results` with this version, which puts every decoded packet on the queue. The `finally` block queues `None` however the loop ends, so the player finishes the remaining audio and stops instead of waiting forever:

```python theme={null}
async def receive_results(ws, audio: asyncio.Queue) -> None:
    pending = {}  # Concluded text per language, buffered until a sentence ends

    def handle_update(label: str, segments: list) -> None:
        text = pending.get(label, "") + "".join(s["text"] for s in segments)
        if text.rstrip().endswith((".", "!", "?")):
            print(f"[{label}] {text.strip()}")
            text = ""
        pending[label] = text

    try:
        async for message in ws:
            data = json.loads(message)
            if "source_transcript_update" in data:
                handle_update("source", data["source_transcript_update"]["concluded"])
            elif "target_transcript_update" in data:
                update = data["target_transcript_update"]
                handle_update(update["language"], update["concluded"])
            elif "target_media_chunk" in data:
                # Raw PCM has no header packets, so every packet is playable audio
                for packet in data["target_media_chunk"]["data"]:
                    await audio.put(base64.b64decode(packet))
            elif "end_of_stream" in data:
                # The very last message: flush any unfinished sentences and exit
                for label, text in pending.items():
                    if text.strip():
                        print(f"[{label}] {text.strip()}")
                return
            elif "error" in data:
                raise RuntimeError(f"Voice API error: {data['error']['error_message']}")
    finally:
        await audio.put(None)
```

Finally, create the queue in `main` and run the player next to the other two tasks:

```python theme={null}
audio = asyncio.Queue()
async with websockets.connect(url) as ws:
    print("Connected. Speak now (Ctrl+C to stop)...")
    await asyncio.gather(
        send_microphone_audio(ws, stop),
        receive_results(ws, audio),
        play_translated_speech(audio),
    )
```

### Run it with translated speech

Here's the complete script with all the changes from this section. Save it as `live_speech_translation.py` if you want to keep the text-only version, and replace `YOUR_AUTH_KEY` with your DeepL API key:

```python live_speech_translation.py [expandable] theme={null}
import asyncio
import base64
import json
import signal

import requests
import sounddevice
import websockets

AUTH_KEY = "YOUR_AUTH_KEY"
SESSION_ENDPOINT = "https://api.deepl.com/v3/voice/realtime"
TARGET_LANGUAGES = ["de", "fr"]
SAMPLE_RATE = 16000  # Must match the rate declared in source_media_content_type
OUTPUT_SAMPLE_RATE = 24000  # Must match the rate declared in target_media_content_type
CHUNK_FRAMES = 3200  # 200 ms per chunk at 16 kHz
RECORD_SECONDS = 30  # Safety cap; Ctrl+C stops recording earlier


def create_session() -> dict:
    response = requests.post(
        SESSION_ENDPOINT,
        headers={"Authorization": f"DeepL-Auth-Key {AUTH_KEY}"},
        json={
            "source_media_content_type": "audio/pcm;encoding=s16le;rate=16000",
            "target_languages": TARGET_LANGUAGES,
            "target_media_languages": ["de"],
            "target_media_content_type": "audio/pcm;encoding=s16le;rate=24000",
        },
    )
    response.raise_for_status()
    return response.json()


async def send_microphone_audio(ws, stop: asyncio.Event) -> None:
    stream = sounddevice.RawInputStream(
        samplerate=SAMPLE_RATE, channels=1, dtype="int16"
    )
    stream.start()
    try:
        for _ in range(RECORD_SECONDS * SAMPLE_RATE // CHUNK_FRAMES):
            if stop.is_set():
                break
            # Read in a worker thread so receiving continues while we block
            data, _overflowed = await asyncio.to_thread(stream.read, CHUNK_FRAMES)
            encoded = base64.b64encode(bytes(data)).decode("ascii")
            await ws.send(json.dumps({"source_media_chunk": {"data": encoded}}))
    finally:
        stream.stop()
        stream.close()
    print("Finalizing transcripts...")
    await ws.send(json.dumps({"end_of_source_media": {}}))


async def play_translated_speech(audio: asyncio.Queue) -> None:
    stream = sounddevice.RawOutputStream(
        samplerate=OUTPUT_SAMPLE_RATE, channels=1, dtype="int16"
    )
    stream.start()
    try:
        while (pcm := await audio.get()) is not None:
            await asyncio.to_thread(stream.write, pcm)
    finally:
        stream.stop()
        stream.close()


async def receive_results(ws, audio: asyncio.Queue) -> None:
    pending = {}  # Concluded text per language, buffered until a sentence ends

    def handle_update(label: str, segments: list) -> None:
        text = pending.get(label, "") + "".join(s["text"] for s in segments)
        if text.rstrip().endswith((".", "!", "?")):
            print(f"[{label}] {text.strip()}")
            text = ""
        pending[label] = text

    try:
        async for message in ws:
            data = json.loads(message)
            if "source_transcript_update" in data:
                handle_update("source", data["source_transcript_update"]["concluded"])
            elif "target_transcript_update" in data:
                update = data["target_transcript_update"]
                handle_update(update["language"], update["concluded"])
            elif "target_media_chunk" in data:
                # Raw PCM has no header packets, so every packet is playable audio
                for packet in data["target_media_chunk"]["data"]:
                    await audio.put(base64.b64decode(packet))
            elif "end_of_stream" in data:
                # The very last message: flush any unfinished sentences and exit
                for label, text in pending.items():
                    if text.strip():
                        print(f"[{label}] {text.strip()}")
                return
            elif "error" in data:
                raise RuntimeError(f"Voice API error: {data['error']['error_message']}")
    finally:
        await audio.put(None)


async def main() -> None:
    stop = asyncio.Event()
    try:
        asyncio.get_running_loop().add_signal_handler(signal.SIGINT, stop.set)
    except NotImplementedError:
        pass  # Windows: Ctrl+C raises KeyboardInterrupt instead

    session = create_session()
    url = f"{session['streaming_url']}?token={session['token']}"
    audio = asyncio.Queue()
    async with websockets.connect(url) as ws:
        print("Connected. Speak now (Ctrl+C to stop)...")
        await asyncio.gather(
            send_microphone_audio(ws, stop),
            receive_results(ws, audio),
            play_translated_speech(audio),
        )
    print("Done. All transcripts are final.")


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        pass
```

Put on your headphones and run it:

```bash theme={null}
python live_speech_translation.py
```

The terminal shows the same transcript and translations as before. A moment after each sentence, you hear it spoken in German. The audio contains only speech, so playback pauses whenever you do.

## Simulate a live stream from a file

If you don't have a microphone, or you want reproducible input while developing, stream a pre-recorded file at real-time pace instead. Set `"source_media_content_type": "audio/auto"` in the session request so the format is detected, and swap `send_microphone_audio` for a reader that paces itself:

```python theme={null}
async def send_file_audio(ws, path: str, stop: asyncio.Event) -> None:
    with open(path, "rb") as audio_file:
        while chunk := audio_file.read(6400):
            if stop.is_set():
                break
            encoded = base64.b64encode(chunk).decode("ascii")
            await ws.send(json.dumps({"source_media_chunk": {"data": encoded}}))
            # Pace the upload to simulate live audio
            await asyncio.sleep(0.2)
    print("Finalizing transcripts...")
    await ws.send(json.dumps({"end_of_source_media": {}}))
```

Any recording of speech in a [supported format](/docs/voice/voice-api-requirements#supported-audio-formats) works, for example an MP3 of a podcast episode.

> [!WARNING]
>
> Don't send audio faster than 2x real-time. Uploading a file as fast as the network allows triggers rate limits and terminates the session.

## Next steps

* See the [WebSocket Streaming reference](/api-reference/voice/websocket-streaming) for the complete message schema and all event types.
* To understand the session flow and token lifecycle in depth, see [Understanding Voice Sessions](/docs/voice/understanding-voice-sessions).
* To choose a voice or another audio format for translated speech, see the [Request Session reference](/api-reference/voice/request-session).
* To reduce bandwidth with MessagePack instead of JSON, see [Message Encoding](/docs/voice/message-encoding).
* For a fuller command-line version of this program, including glossary and formality options, see the [DeepL Voice CLI example](https://github.com/DeepL/deepl-python/tree/main/examples/voice/cli).
* To apply a custom glossary to your translations, see the [Glossaries API](/docs/customize/managing-glossaries).


# Supported Voice Languages
Source: https://developers.deepl.com/docs/voice/supported-voice-languages

Language availability for the DeepL Voice API: transcription, translation, and translated speech support per language.

Translation is always provided by DeepL. For some languages, transcription and translated speech are provided by external service partners. All source languages can be translated into any target language.

> | **Language** | **Transcription** | **Translation** | **Translated Speech** |
> | :- | :-: | :-: | :-: |
> | Arabic | ⎋ | ✓ | ⎋ |
> | Bengali | ⎋ | ✓ | — |
> | Bulgarian | ⎋ | ✓ | ⎋ |
> | Catalan | ⎋ | ✓ | ⎋ |
> | Chinese (simplified) | ✓ | ✓ | ✓ |
> | Chinese (traditional) | ✓ | ✓ | ✓ |
> | Croatian | ⎋ | ✓ | ⎋ |
> | Czech | ✓ | ✓ | ⎋ |
> | Danish | ⎋ | ✓ | ⎋ |
> | Dutch | ✓ | ✓ | ✓ |
> | English (American) | ✓ | ✓ | ✓ |
> | English (British) | ✓ | ✓ | ✓ |
> | Estonian | ⎋ | ✓ | — |
> | Finnish | ⎋ | ✓ | ⎋ |
> | French | ✓ | ✓ | ✓ |
> | French (Canadian) | ✓ | ✓ | ⎋ |
> | Galician | ⎋ | ✓ | ⎋ |
> | German | ✓ | ✓ | ✓ |
> | Greek | ⎋ | ✓ | ⎋ |
> | Hebrew | ⎋ | ✓ | ⎋ |
> | Hindi | ⎋ | ✓ | ⎋ |
> | Hungarian | ⎋ | ✓ | ⎋ |
> | Indonesian | ✓ | ✓ | ⎋ |
> | Irish | ⎋ | ✓ | — |
> | Italian | ✓ | ✓ | ✓ |
> | Japanese | ✓ | ✓ | ✓ |
> | Korean | ✓ | ✓ | ✓ |
> | Latvian | ⎋ | ✓ | — |
> | Lithuanian | ⎋ | ✓ | — |
> | Malay | ⎋ | ✓ | ⎋ |
> | Maltese | ⎋ | ✓ | — |
> | Norwegian (bokmål) | ⎋ | ✓ | ⎋ |
> | Polish | ✓ | ✓ | ✓ |
> | Portuguese (Brazilian) | ✓ | ✓ | ✓ |
> | Portuguese (European) | ✓ | ✓ | ✓ |
> | Romanian | ✓ | ✓ | ⎋ |
> | Russian | ✓ | ✓ | ✓ |
> | Slovak | ⎋ | ✓ | ⎋ |
> | Slovenian | ⎋ | ✓ | ⎋ |
> | Spanish | ✓ | ✓ | ✓ |
> | Spanish (Latin American) | ✓ | ✓ | ⎋ |
> | Swedish | ✓ | ✓ | ✓ |
> | Tagalog | ⎋ | ✓ | ⎋ |
> | Tamil | ⎋ | ✓ | ⎋ |
> | Thai | ⎋ | ✓ | ⎋ |
> | Turkish | ✓ | ✓ | ✓ |
> | Ukrainian | ✓ | ✓ | ⎋ |
> | Vietnamese | ⎋ | ✓ | ⎋ |
>
> ✓ provided by DeepL / ⎋ provided by an external service partner / — not available

> [!WARNING]
>
> Transcription provided by external service partners (marked with ⎋) cannot yet auto-detect the source language,
> which you must therefore specify explicitly.

To retrieve supported languages and feature availability programmatically, call [`GET /v3/languages?resource=voice`](/docs/languages/using-the-languages-api) and check for the `transcription` and `translated_speech` feature keys. The `external` flag on these features indicates if they are provided by an external service partner.

For audio format support and session limits, see [Voice API Requirements](/docs/voice/voice-api-requirements).


# Understanding Voice Sessions
Source: https://developers.deepl.com/docs/voice/understanding-voice-sessions

Understand the lifecycle of a DeepL Voice API session: how connections are established, how tokens secure reconnection, and how audio and results flow.

This page explains the lifecycle of a Voice API session: how a connection is established, how tokens keep it secure and resumable, and how audio and results flow over the WebSocket. To run this flow end to end first, see the [Real-Time Voice Quickstart](/docs/voice/real-time-voice-quickstart).

## The two-step connection flow

Every Voice API session starts with two steps:

1. [Request a session](/api-reference/voice/request-session) with a POST request to `/v3/voice/realtime`. This is where authentication happens and where you fix the session's configuration: audio formats, source and target languages, glossaries, spoken terms, [message encoding](/docs/voice/message-encoding), and an optional [custom reporting tag](/docs/learning-how-tos/examples-and-guides/how-to-use-custom-reporting-tags). The response contains an ephemeral streaming URL and a token, both valid for one-time use.
2. [Open a WebSocket connection](/api-reference/voice/websocket-streaming) to the streaming URL, passing the token as a query parameter. All audio and results are exchanged as messages over this connection.

Splitting setup from streaming keeps your API key out of the WebSocket handshake and settles all configuration before any audio flows. The WebSocket itself carries only audio and results.

> **Show flow diagram**
>
> ```mermaid theme={null}
> sequenceDiagram
>     participant Client
>     participant Voice API
>
>     Note over Client,Voice API: Step 1: Request Session (POST)
>
>     Client->>Voice API: Configuration options
>     Voice API->>Client: Streaming URL and token
>
>     Note over Client,Voice API: Step 2: Start Streaming (WebSocket)
>
>     Client->>Voice API: Establish WebSocket connection<br/>using the streaming URL
>
>     Note over Client,Voice API: WebSocket Connection Established
>
>     Client<<->>Voice API: Bidirectional message exchange:   <br/>Send audio, receive transcripts,<br/>translations, and speech
>
>     Note over Client,Voice API: Stream Closed
> ```

## Tokens and reconnection

Network connections are unreliable, so the Voice API is built around resumable sessions. A session is identified and secured by its token, which rotates over its lifetime: the initial session response and every reconnection response contain a new token, and your client should always keep the most recent one.

If the connection drops, you exchange the latest token for a new streaming URL and token via [GET `/v3/voice/realtime`](/api-reference/voice/reconnect-session), then reconnect and pick up where you left off. Session state, including configuration and translation context, is preserved across reconnections.

Two security properties follow from the token design:

* Each token and streaming URL is valid for one-time use. Using a token more than once to open a WebSocket connection terminates the session immediately.
* Only the latest token can request a reconnection. Presenting an outdated token invalidates the session.

Requesting a reconnection token while a connection is still active disconnects that connection, so only reconnect after the existing connection has closed. The API keeps connections open for as long as possible, but your client must handle disconnects and reconnect to continue the session. See [session limits](/docs/voice/voice-api-requirements#session-limits) for details.

## How audio and results flow

Once connected, you send audio continuously as [source media chunk](/api-reference/voice/websocket-streaming) messages. Smaller chunks mean lower latency, because the API can start processing sooner. When the audio ends, an [end of source media](/api-reference/voice/websocket-streaming) message tells the API to finalize all pending results. Keep audio flowing: a session with no incoming data times out and is terminated.

As audio is processed, transcripts and translations arrive incrementally via [source transcript updates](/api-reference/voice/websocket-streaming) and [target transcript updates](/api-reference/voice/websocket-streaming). Each update distinguishes two kinds of segments:

* **Concluded segments**: finalized text that will not change. These are sent once and remain fixed.
* **Tentative segments**: preliminary text that may be refined as more audio context becomes available.

Applications typically append concluded segments to the running transcript and display tentative segments as provisional text that gets replaced by later updates.

### Translated speech

When a translated speech target is configured, synthesized audio arrives incrementally as [target media chunks](/api-reference/voice/websocket-streaming). To save bandwidth, the stream contains only speech, without silence or padding, so there are gaps with no data whenever the speaker pauses. Each chunk carries text and audio duration information, which you can use to highlight the currently spoken text or to subtitle the audio output.

By default, each target language is spoken by its own language-specific voice, and you can instead request a preset male or female voice on the [session request](/api-reference/voice/request-session). **Speaker match** is a third option: it produces translated speech with a voice close to the original speaker's voice. Speaker match works only for target languages whose translated speech is provided by DeepL, not for languages provided through external service partners. See [Supported Voice Languages](/docs/voice/supported-voice-languages) for which languages qualify. Requesting speaker match for any other target language is not an error: the session starts as usual and that language is spoken by a preset voice instead, so check the language table rather than relying on a failed request.

> **Show detailed message flow**
>
> ```mermaid theme={null}
> sequenceDiagram
>     participant Client
>     participant Voice API
>
>     Note over Client,Voice API: WebSocket Connection Established
>
>     par
>       loop Send audio data
>         Client->>Voice API: source_media_chunk
>       end
>     and
>       loop Receive updates
>         Voice API-->>Client: source_transcript_update
>       end
>     and Per target language
>       loop Receive updates
>         Voice API-->>Client: target_transcript_update
>       end
>     and Per target language
>       loop Receive translated speech
>         Voice API-->>Client: target_media_chunk
>       end
>     end
>
>     Client->>Voice API: end_of_source_media
>
>     par
>       loop Final updates
>         Voice API-->>Client: source_transcript_update
>       end
>     and Per target language
>       loop Final updates
>         Voice API-->>Client: target_transcript_update
>       end
>     and Per target language
>       loop Final audio chunks
>         Voice API-->>Client: target_media_chunk
>       end
>     end
>
>     Voice API-->>Client: end_of_source_transcript
>
>     Voice API-->>Client: end_of_target_transcript<br/>(once per target language)
>
>     Voice API-->>Client: end_of_target_media<br/>(once per target language)
>
>     Voice API-->>Client: end_of_stream
>
>     Note over Client,Voice API: Stream Closed
> ```
>
> `par` means parallel execution and `loop` means looped execution.


# Voice API Requirements
Source: https://developers.deepl.com/docs/voice/voice-api-requirements

Audio format requirements and session limits for the DeepL Voice API: supported codecs and containers, chunk sizes, and connection rules.

## Supported audio formats

The API supports common combinations of streaming codecs and containers with a single-channel (mono) audio stream.

| **Audio Codec** | **Audio Container** | **Recommended Bitrate** |
| :- | :- | :- |
| **PCM**  | **-** | **256 kbps (16kHz), default recommendation** |
| **OPUS**  | **Matroska / MPEG-TS / Ogg / WebM** | **32 kbps, recommended for low bandwidth scenarios** |
| AAC | Matroska / MPEG-TS | 96 kbps |
| FLAC | FLAC / Matroska / Ogg | 256 kbps (16kHz) |
| MP3 | MPEG / Matroska | 128 kbps |

For the detailed list of supported input audio formats, see [Source Media Content Type](/api-reference/voice/request-session#body-source-media-content-type). For supported output audio formats, see [Target Media Content Type](/api-reference/voice/request-session#body-target-media-content-type).

## Session limits

* Maximum 5 translation targets per session (including translated speech targets)
* Maximum 1 translated speech target per session
* Maximum 10 glossaries per session ([`glossary_ids`](/api-reference/voice/request-session), ordered by priority)
* Audio chunk size: should not exceed 100 kilobytes or 1 second duration
* Recommended chunk duration: 50-250 milliseconds for low latency
* Audio stream speed: maximum 2x real-time
* Timeout: if no data is received for 30 seconds, the session is terminated
* Connection duration: the API keeps connections open for as long as possible, but connections can close at any time. Your client must handle disconnects and [reconnect](/api-reference/voice/reconnect-session) to continue the session
* Using any given token more than once to establish a WebSocket connection terminates the associated session immediately for security reasons

If you need more translation targets or translated speech targets than these limits allow, open multiple concurrent sessions over the same source audio.

For language availability, see [Supported Voice Languages](/docs/voice/supported-voice-languages).