Tutorials

DeepL API: Integration Tutorial

Updated 2026-03-10

DeepL API: Integration Tutorial

DeepL offers one of the cleanest translation APIs available, with the highest quality output for European languages. This tutorial covers everything from getting your API key to advanced features like glossaries, formality control, and document translation.

Translation comparisons are based on automated metrics and editorial evaluation. Quality varies by language pair and content type.

Choose Your Plan

FeatureDeepL API FreeDeepL API Pro
PriceFree$5.49/month + $25/1M chars
Character limit500K/monthUnlimited
API endpointapi-free.deepl.comapi.deepl.com
Document translationLimitedFull
GlossaryYesYes
FormalityYesYes
Credit card requiredNoYes

Recommendation: Start with Free for testing and development. Switch to Pro for production.

Step 1: Get Your API Key

  1. Go to deepl.com/pro-api
  2. Sign up for DeepL API Free or Pro
  3. Navigate to your account settings
  4. Copy your authentication key

Step 2: Make Your First API Call

Using curl

curl -X POST "https://api-free.deepl.com/v2/translate" \
  -H "Authorization: DeepL-Auth-Key YOUR_API_KEY" \
  -d "text=Hello, how are you?" \
  -d "target_lang=ES"

Using Python (requests)

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api-free.deepl.com"  # Use api.deepl.com for Pro

response = requests.post(
    f"{BASE_URL}/v2/translate",
    headers={"Authorization": f"DeepL-Auth-Key {API_KEY}"},
    data={
        "text": "Hello, how are you?",
        "target_lang": "ES"
    }
)

result = response.json()
print(result["translations"][0]["text"])
# "Hola, ¿cómo estás?"

Using the Official Python SDK

pip install deepl
import deepl

translator = deepl.Translator("YOUR_API_KEY")
result = translator.translate_text("Hello, how are you?", target_lang="ES")
print(result.text)          # "Hola, ¿cómo estás?"
print(result.detected_source_lang)  # "EN"

Step 3: Key API Features

Formality Control

Control the formality level of translations (available for DE, FR, ES, IT, NL, PL, PT, RU, JA):

# Formal
result = translator.translate_text(
    "How are you?",
    target_lang="DE",
    formality="more"
)
print(result.text)  # "Wie geht es Ihnen?" (formal Sie)

# Informal
result = translator.translate_text(
    "How are you?",
    target_lang="DE",
    formality="less"
)
print(result.text)  # "Wie geht es dir?" (informal du)

Source Language Specification

Specify the source language or let DeepL auto-detect:

# Auto-detect (default)
result = translator.translate_text("Bonjour", target_lang="EN-US")

# Explicit source
result = translator.translate_text(
    "Bonjour",
    source_lang="FR",
    target_lang="EN-US"
)

Target Language Variants

DeepL distinguishes between English variants and Portuguese variants:

# American English
result = translator.translate_text("Couleur", target_lang="EN-US")
# "Color"

# British English
result = translator.translate_text("Couleur", target_lang="EN-GB")
# "Colour"

# Brazilian Portuguese
result = translator.translate_text("Hello", target_lang="PT-BR")

# European Portuguese
result = translator.translate_text("Hello", target_lang="PT-PT")

Preserving Formatting

Handle XML/HTML content:

result = translator.translate_text(
    "<p>Hello <b>world</b></p>",
    target_lang="DE",
    tag_handling="html"
)
print(result.text)  # "<p>Hallo <b>Welt</b></p>"

Step 4: Set Up Glossaries

Glossaries ensure consistent terminology translation:

# Create a glossary
glossary = translator.create_glossary(
    "My Glossary",
    source_lang="EN",
    target_lang="DE",
    entries={
        "API key": "API-Schlüssel",
        "repository": "Repository",
        "deploy": "bereitstellen"
    }
)

# Use the glossary in translation
result = translator.translate_text(
    "Enter your API key to deploy the repository.",
    target_lang="DE",
    glossary=glossary
)

Glossary limitations:

  • Not all language pairs support glossaries (check the API docs)
  • Maximum entries vary by plan
  • Glossary entries are exact matches (no fuzzy matching)

Step 5: Document Translation

DeepL can translate entire documents while preserving formatting:

# Translate a document
translator.translate_document_from_filepath(
    "report.docx",
    "report_translated.docx",
    target_lang="FR"
)

Supported formats: .docx, .pptx, .xlsx, .pdf, .htm/.html, .txt

Step 6: Check Usage

Monitor your API usage to stay within limits:

usage = translator.get_usage()
print(f"Characters used: {usage.character.count}")
print(f"Character limit: {usage.character.limit}")

Error Handling

import deepl

try:
    result = translator.translate_text("Hello", target_lang="ES")
except deepl.AuthorizationException:
    print("Invalid API key")
except deepl.QuotaExceededException:
    print("Character quota exceeded")
except deepl.TooManyRequestsException:
    print("Rate limit hit, retrying...")
    import time
    time.sleep(1)
    result = translator.translate_text("Hello", target_lang="ES")
except deepl.DeepLException as e:
    print(f"Translation failed: {e}")

Supported Languages

DeepL supports approximately 33 languages. Key supported languages: Bulgarian, Chinese (Simplified/Traditional), Czech, Danish, Dutch, English (US/GB), Estonian, Finnish, French, German, Greek, Hungarian, Indonesian, Italian, Japanese, Korean, Latvian, Lithuanian, Norwegian, Polish, Portuguese (BR/PT), Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Turkish, Ukrainian.

Notable gaps: Arabic, Hindi, Thai, Vietnamese, and most African languages are not supported. For these, consider Google Translate or NLLB-200. See our complete model comparison for coverage details.

When to Use DeepL vs Other Translation APIs

DeepL excels at European language pairs and produces the most natural-sounding output for languages like German, French, Spanish, and Portuguese. However, it is not the right choice for every project. If you need broad language coverage (100+ languages), Google Translate or NLLB-200 are better options. If you need the highest quality for creative or marketing content, GPT-4 and Claude offer more contextual translations but at higher cost and latency. For a side-by-side quality analysis, read Google Translate vs DeepL vs AI.

For developers evaluating multiple APIs, the key decision factors are language coverage, cost per character, latency requirements, and whether you need features like formality control or glossary support. DeepL’s Free tier (500K chars/month, no credit card) makes it easy to benchmark against other options before committing. Our translation quality metrics guide explains how to measure and compare output quality across providers.

Key Takeaways

  • DeepL’s API is clean, well-documented, and easy to integrate. The official Python SDK simplifies development.
  • Formality control and glossary features are particularly valuable for professional translation.
  • Document translation with formatting preservation is a standout feature.
  • The main limitation is language coverage (approximately 33 languages). For broader coverage, combine DeepL with Google Translate or NLLB-200.
  • The Free tier (500K chars/month, no credit card) is generous for development and small projects.

Next Steps