DeepL API 免费额度申请：一次性 100 万字符翻译接口怎么领

DeepL 提供的是翻译接口，并非 OpenAI 式的对话补全接口，因此没有 /v1/chat/completions 这类路径，也没有可选的模型名，翻译能力由 DeepL 自研引擎直接提供，无法直接塞进 OpenAI 兼容客户端，需要在业务层自行包一层服务。免费档的 base_url 为 https://api-free.deepl.com/v2/，付费档换成 https://api.deepl.com/v2/。

文本翻译调用

向 /v2/translate 发 POST 请求，鉴权用请求头 Authorization: DeepL-Auth-Key 你的密钥。可以直接复制下面这段 curl 验证连通性：

curl -X POST "https://api-free.deepl.com/v2/translate" \
  -H "Authorization: DeepL-Auth-Key 你的API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": ["Hello, world!", "How are you?"],
    "source_lang": "EN",
    "target_lang": "ZH"
  }'

关键参数说明：text 是待翻译文本数组，可以一次传多条，计费按字符总量算；target_lang 必填，中文写 ZH，英文 EN，德语 DE；source_lang 可省略，省略时自动识别语种；formality 控制正式程度（more 或 less）；glossary_id 用于绑定术语表，保证专有名词译法统一；tag_handling 设为 html 可保留标签结构而不破坏页面。返回结果在 translations[].text 中，同时带有 billed_characters 字段，方便核对扣量。

Python 调用示例，密钥通过环境变量注入，避免写死在代码里：

import os
import requests

resp = requests.post(
    "https://api-free.deepl.com/v2/translate",
    headers={"Authorization": "DeepL-Auth-Key " + os.environ["DEEPL_AUTH_KEY"]},
    json={"text": ["Good morning"], "target_lang": "ZH"},
    timeout=30,
)
print(resp.json()["translations"][0]["text"])

文档翻译

先 POST /v2/document 上传 DOCX 或 PDF 文件，拿到 document_id 与 document_key；再轮询 /v2/document/{document_id} 查询处理状态，状态变为 done 后通过同一接口取回译文。文档翻译消耗的字符同样从免费额度中扣除。

额度耗尽与限流的排查

典型表现：返回 HTTP 456 表示免费字符已经用尽；返回 429 表示请求过于频繁触发限流；返回 403 多为密钥无效，或把免费 Key 发到了 api.deepl.com。建议按以下顺序排查：

1. 核对请求域名是否为 api-free.deepl.com，免费 Key 与付费域名不匹配。
2. 核对请求头格式，必须是 DeepL-Auth-Key 加一个空格再加完整密钥，不要漏掉前缀。
3. 到控制台用量页查看剩余字符与近期消耗，具体数值以控制台实际显示为准。
4. 遇到 429 时按指数退避重试并降低并发，批量翻译建议分批提交而非一次塞上万条。

额度用尽后接口不会自动恢复，也不会按月重置，需要升级到付费方案才能继续调用。上线前建议先用小批量文本跑通流程，并记录每千字符的消耗，便于估算长期成本。