PDF Translation API: Complete Integration Guide with Code

First API Call: Stuck on Auth for Two Hours

First time calling the PDFTranslate API: followed the docs step by step, got 401 Unauthorized every time. Took two hours to find the issue: API Key goes in the HTTP Authorization header, not the request body.

Small detail, huge time waste. This guide skips every pitfall I found.

Prerequisites

PDFTranslate account, API Key (from Settings → API), cURL or any HTTP client.

Step 1: Get Your API Key

Login → Settings → API → Generate New Key. Save it — it will not be shown again after refresh.

Step 2: Upload File

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://api.pdftranslate.app/v1"

resp = requests.post(
    f"{BASE_URL}/upload",
    headers={"Authorization": f"Bearer {API_KEY}"},
    files={"file": ("document.pdf", open("document.pdf","rb"), "application/pdf")}
)
file_id = resp.json()["file_id"]

Step 3: Start Translation

payload = {
    "file_id": file_id,
    "source_lang": "en",
    "target_lang": "zh",
    "engine": "glm-4.5-air"  # or deepseek-v3, glm-4.7-flash
}
resp = requests.post(f"{BASE_URL}/translate",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json=payload)
task_id = resp.json()["task_id"]

Step 4: Poll or Webhook

# Option 1: Poll (simple)
import time, requests
while True:
    s = requests.get(f"{BASE_URL}/status/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}).json()
    if s["state"] == "completed":
        print(s["download_url"]); break
    time.sleep(5)

# Option 2: Webhook (recommended)
payload["webhook_url"] = "https://your-server.com/webhook/pdftranslate"

Common Errors

401: API Key in wrong place. Must be in Authorization: Bearer header, not body.

413: File over 50MB. Split or compress the file.

422: Unsupported format. Must be PDF/DOCX/PPTX/TXT.