Skip to main content

​
Endpoint

POST /v1/translate
This endpoint requires a DeepL Pro account and uses the dl_session cookie for authentication. It provides enhanced translation capabilities available to Pro users.

​
Authentication

​
Access Token

If an access token is configured on the server, include it in one of the following ways: 
POST /v1/translate?token=your_access_token

​
DeepL Pro Session

​
Cookie
string
required
DeepL Pro session cookie: dl_session=your_session_valueImportant: The session value must NOT contain a period (.). Sessions with periods indicate free accounts, not Pro accounts.

​
Request Body

​
text
string
required
The text to be translated. Can contain multiple sentences or paragraphs.
​
source_lang
string
The source language code (e.g., “EN”, “DE”, “FR”, “ZH”). Use “auto” or omit for automatic detection.
​
target_lang
string
required
The target language code (e.g., “EN”, “DE”, “FR”, “ZH”).
​
tag_handling
string
Specifies how to handle tags in the text. Allowed values: html or xml. Leave empty for plain text.

​
Response

​
code
number
HTTP status code (200 for success)
​
id
number
Unique identifier for the translation request
​
data
string
The primary translated text
​
alternatives
array
Array of alternative translations
​
source_lang
string
Detected or specified source language
​
target_lang
string
Target language for the translation
​
method
string
Translation method used by the API (“Pro” for this endpoint)

​
Examples

curl -X POST http://localhost:1188/v1/translate \
  -H "Content-Type: application/json" \
  -H "Cookie: dl_session=your_session_value" \
  -d '{
    "text": "Hello, world!",
    "source_lang": "EN",
    "target_lang": "DE"
  }'

​
Success Response

{
  "code": 200,
  "id": 1234567890,
  "data": "Hallo, Welt!",
  "alternatives": [
    "Hallo Welt!",
    "Servus, Welt!"
  ],
  "source_lang": "EN",
  "target_lang": "DE",
  "method": "Pro"
}

​
Error Responses

{
  "code": 400,
  "message": "Invalid tag_handling value. Allowed values are 'html' and 'xml'."
}
Returned when tag_handling is set to a value other than html or xml.
{
  "code": 401,
  "message": "No dl_session Found"
}
Returned when no dl_session cookie is provided in the request.
{
  "code": 401,
  "message": "Your account is not a Pro account. Please upgrade your account or switch to a different account."
}
Returned when the dl_session contains a period (.), indicating a free account rather than a Pro account.
{
  "code": 401,
  "message": "Invalid access token"
}
Returned when the provided access token doesn’t match the server configuration.

​
Notes

  • Requires DeepL Pro Account: This endpoint only works with valid Pro account sessions
  • Session Validation: Free account sessions (containing .) are rejected
  • Cookie Priority: If both config dl_session and request Cookie header are provided, the header takes precedence
  • Enhanced Quality: Pro accounts provide higher quality translations and additional features
  • The alternatives field provides multiple translation options for better context

Build docs developers (and LLMs) love

Get started for freeTalk to us