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

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

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:

<CodeGroup>
  ```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));
  ```
</CodeGroup>

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