Translate Document API

Workflow Overview

Document translation is an asynchronous three-step process:

1. Upload the document to be translated
2. Poll the status until translation is complete
3. Download the translated document once ready

Step 1: Upload Document

Endpoint

POST /v2/document

Base URLs

https://api-free.deepl.com/v2/document  (Free API)
https://api.deepl.com/v2/document       (Pro / Enterprise)

Parameters

Parameter	Type	Required	Description
file	binary	Yes	The document file to translate. Must be sent as multipart/form-data.
target_lang	string	Yes	Target language code (e.g., "DE", "FR", "JA").
source_lang	string	No	Source language code. If omitted, auto-detected.
filename	string	No	Custom filename for the translated document. If omitted, auto-generated.
formality	string	No	Formality preference: "default", "more", "less", "prefer_more", "prefer_less".
glossary_id	string	No	Glossary ID(s) to apply. Multiple glossaries can be specified.

Supported Formats

Format	Extensions	Max File Size
PDF	.pdf	30 MB
Word	.docx	30 MB
PowerPoint	.pptx	30 MB
Excel	.xlsx	30 MB
HTML	.html, .htm	30 MB
Text	.txt	30 MB
XLIFF	.xliff, .xlf	30 MB
IDML	.idml	30 MB
SRT	.srt	30 MB

Upload Request Example (cURL)

curl -X POST 'https://api-free.deepl.com/v2/document' \
  -H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
  -F 'file=@document.docx' \
  -F 'target_lang=DE' \
  -F 'source_lang=EN' \
  -F 'formality=prefer_more'

Upload Response

{
  "document_id": "ABC123XYZ...",
  "document_key": "DEF456UVW..."
}

Step 2: Check Translation Status

Endpoint

POST /v2/document/{document_id}

Status Request Example (cURL)

curl -X POST 'https://api-free.deepl.com/v2/document/ABC123XYZ...' \
  -H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document_key": "DEF456UVW..."
  }'

Status Response

{
  "document_id": "ABC123XYZ...",
  "status": "translating",
  "seconds_remaining": 5,
  "billed_characters": 1234
}

When translation is complete, the status changes to "done":

{
  "document_id": "ABC123XYZ...",
  "status": "done",
  "seconds_remaining": 0,
  "billed_characters": 1234
}

Step 3: Download Translated Document

Endpoint

POST /v2/document/{document_id}/result

Download Request Example (cURL)

curl -X POST 'https://api-free.deepl.com/v2/document/ABC123XYZ.../result' \
  -H 'Authorization: DeepL-Auth-Key YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document_key": "DEF456UVW..."
  }' \
  -o translated_document.docx

This endpoint returns the binary content of the translated document. The response includes the Content-Type header indicating the original document format.

Polling Best Practices

• Use exponential backoff between status checks — start with 1 second and increase gradually.
• Most documents translate within 5–30 seconds, depending on file size and complexity.
• Always check the status field before attempting to download. Available statuses: "queued", "translating", "done", "error".
• If the status is "error", check the error_message field for details.
• Translated documents are stored for a limited time. Download promptly after translation completes.

Error Handling

• 400 — Invalid file format or parameters
• 403 — Invalid or missing API key
• 404 — Document ID not found
• 413 — File exceeds maximum size limit
• 456 — Quota exceeded
• 429 — Rate limit exceeded