> ## Documentation Index
> Fetch the complete documentation index at: https://deepl-c950b784-docs-agentic-readiness-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## 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.

# 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).