有道翻译 API 怎么接？用一个最小请求验证 AppKey、签名和返回值

直接答案：第一次接有道翻译 API，不要先做完整网站。先完成一个最小闭环：拿到 AppKey 和应用密钥 → 生成 salt、curtime 和 v3 签名 → 向当前文本翻译接口发送一条短文本 → 保存原始 JSON。这个最小请求能成功，后面接数据库、表单、队列才有意义。

这里只讨论开发调用。普通用户如果只是需要桌面端，可直接从有道翻译下载入口开始；开发者则继续下面的 AppKey、签名和最小请求验证。

先确定你接的是“当前接口”，不要拿旧示例直接改

有道智云不同服务的参数和签名规则并不完全相同。当前自然语言文本翻译文档使用应用 ID（AppKey）、salt、curtime、sign、signType 等参数，文本翻译接口示例为 https://openapi.youdao.com/v2/api。其他 OCR、文档转换或模型接口可能使用不同字段，因此每换一个服务都要重新核对官方文档，不能假设所有 API 共用完全相同的请求体。

第一步：把密钥留在服务器，不要放进前端

1. 在有道智云应用管理里确认应用 ID 和应用密钥。
2. 把密钥写入服务器环境变量或仅服务器可读配置。
3. 浏览器 JavaScript、公开 Git 仓库、页面源码里不要出现真实 appSecret。
4. 测试日志也不要打印完整密钥。

v3 签名的核心不是“SHA256”三个字，而是 input

当前文本翻译文档的 v3 规则可以概括为：

sign = sha256(appKey + input + salt + curtime + appSecret)

其中待翻译文本长度不超过 20 时，input=q；超过 20 时，使用“前 10 个字符 + 总长度 + 后 10 个字符”。很多 202 签名错误，不是 SHA256 算错，而是 input 截断逻辑、时间戳或编码不一致。

先跑这一条最小 Python 请求

下面示例只用于验证调用链。把 AppKey 和密钥放到环境变量，不要直接写死在代码里：

import os
import time
import uuid
import hashlib
import requests

APP_KEY = os.environ["YOUDAO_APP_KEY"]
APP_SECRET = os.environ["YOUDAO_APP_SECRET"]

q = "今天适合做一个最小请求测试。"
salt = str(uuid.uuid4())
curtime = str(int(time.time()))

def truncate(text):
    if len(text) <= 20:
        return text
    return text[:10] + str(len(text)) + text[-10:]

raw = APP_KEY + truncate(q) + salt + curtime + APP_SECRET
sign = hashlib.sha256(raw.encode("utf-8")).hexdigest()

data = {
    "q": q,
    "from": "auto",
    "to": "en",
    "appKey": APP_KEY,
    "salt": salt,
    "sign": sign,
    "signType": "v3",
    "curtime": curtime,
}

r = requests.post(
    "https://openapi.youdao.com/v2/api",
    data=data,
    timeout=15
)

print(r.status_code)
print(r.text)

测试阶段不要马上写 data["translation"][0]。先打印原始响应，因为失败时最有价值的是 errorCode、错误信息和完整返回结构。

按层判断失败，而不是只说“API 不通”

最小请求成功后，再一层一层加功能

1. 把请求代码封装成函数；
2. 加入连接和读取超时；
3. 记录 errorCode、requestId 和耗时；
4. 加入有限次数的重试，不做无限循环；
5. 再接网站表单、缓存、数据库；
6. 最后才做批量和异步队列。

每加一层都保留最小脚本。以后业务页面报错时，先运行最小脚本：它成功，说明接口基础链路还在；它失败，才回 API 层排查。

这页的边界

普通用户只想翻译几句话，不需要 API；图片 OCR、文本润色和文档转换也各自有独立接口和参数，不能把文本翻译示例硬套过去。本页唯一目标就是让开发者完成“第一个可验证请求”。

签名错误时不要同时改五个变量

如果返回签名相关错误，按固定顺序只改一项：先核对 AppKey，再核对 curtime 是否为当前秒级时间戳，再核对 salt 是否真的参与签名，最后检查 input 截断和 UTF-8 编码。一次同时改多项，即使请求突然成功，你也不知道真正错在哪里。

把“成功响应”保存成基准样本

第一次成功后，把请求参数结构、HTTP 状态、原始 JSON、耗时和当前代码版本一起保存。以后业务系统出问题时，先运行这份基准样本。基准成功而业务失败，问题就在你自己的业务层；基准也失败，才回接口、密钥、网络或服务层检查。

上线前再补两层保护

• 速率与重试边界：失败时不要无上限重试，避免把临时问题放大成大量重复请求。
• 日志脱敏：保留 requestId、错误码、耗时和输入长度即可，不记录完整 appSecret，也不要把用户敏感文本长期写入日志。