适用场景文本翻译是许多国际化应用、内容平台、文档管理工具的基础功能。典型场景包括多语言内容生成将中文知识库自动翻译成英文、日语等用于海外文档。实时辅助翻译在IM工具或CMS中用户输入一段文本后快速返回翻译结果。本地化测试批量验证UI文本在不同语言下的显示效果。学习与实验在开发中快速处理少量文本避免每次去查词典。接口能力边界该文本翻译API支持19种语言互译包括简体中文、繁体中文、英文、日语、韩语、法语、德语、俄语、西班牙语、葡萄牙语、意大利语、荷兰语、瑞典语、丹麦语、芬兰语、波兰语、捷克语、罗马尼亚语、泰语。特别值得注意粤语yue和文言文wyw也作为独立语言代码提供。每次请求可翻译的文本最长5000字超过该长度需要自行拆分。接口的QPS限制为5次/秒超出后返回限流错误。请求参数与鉴权接口地址GET https://v1.apizero.cn/api/translateQuery参数参数名类型必填默认值说明qstring是无待翻译文本最长5000字也可用text作为别名fromstring否zh源语言代码使用百度系代码如日语jp韩语kor法语fratostring否en目标语言代码规则同上语言代码示例语言代码中文简体zh中文繁体cht粤语yue文言文wyw英文en日语jp韩语kor法语fra完整代码表请参考 官方文档。Header鉴权需要在请求头中携带Authorization或X-API-Key二选一值填写你获得的API密钥。建议使用Authorization: Bearer YOUR_API_KEY或X-API-Key: YOUR_API_KEY。curl 接入示例以下是一个完整的可复制curl命令将$APIZERO_API_KEY替换为真实密钥curl -sS \ -X GET \ -H Authorization: Bearer $APIZERO_API_KEY \ https://v1.apizero.cn/api/translate?q你好世界fromzhtoen若使用环境变量存储密钥可直接执行export APIZERO_API_KEYyour_key_here curl -sS -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/translate?q你好世界代码接入示例Python Node.jsPythonrequestsimport requests API_URL https://v1.apizero.cn/api/translate API_KEY your_key_here headers {Authorization: fBearer {API_KEY}} params { q: 你好世界, from: zh, to: en } resp requests.get(API_URL, headersheaders, paramsparams, timeout10) resp.raise_for_status() data resp.json() if data.get(code) 0: print(data[data][target_text]) else: print(Error:, data.get(msg))Node.jsaxiosconst axios require(axios); const API_URL https://v1.apizero.cn/api/translate; const API_KEY your_key_here; axios.get(API_URL, { headers: { Authorization: Bearer ${API_KEY} }, params: { q: 你好世界, from: zh, to: en }, timeout: 10000 }) .then(res { const body res.data; if (body.code 0) { console.log(body.data.target_text); } else { console.error(API错误:, body.msg); } }) .catch(err { console.error(请求失败:, err.message); });返回值解读成功时返回如下结构HTTP 200{ code: 0, msg: 成功, data: { char_count: 4, from: zh, from_name: 中文简体, source_text: 你好世界, target_text: Hello World, to: en, to_name: 英文 }, request_id: abc123 }字段类型说明codeint0 表示成功非0表示错误msgstring状态描述data.char_countint源文本字符数含空格data.fromstring源语言代码data.from_namestring源语言中文名称data.source_textstring源文本原文data.target_textstring翻译结果data.tostring目标语言代码data.to_namestring目标语言中文名称request_idstring请求唯一标识可用于日志排查常见错误码与处理HTTP状态码codemsg原因处理建议200100缺少参数q未提供待翻译文本检查请求中是否包含q或text参数200101语言代码不支持from/to使用了不支持的代码核对语言代码表使用百度系代码200102文本长度超过限制文本超过5000字拆分长文本为多次请求200103翻译失败服务端内部错误重试若持续失败联系支持401300认证失败API Key无效或缺失检查Header中是否正确附带密钥429400请求频率过高超过QPS 5次/秒加入退避重试逻辑500500服务器内部错误后端异常等待后重试注意错误响应中code字段仍在根级data可能为null。需判断code ! 0时按错误处理。工程化注意事项连接池与超时在生产环境中务必设置合理的timeout建议5-10秒并使用连接池默认Keep-Alive。Python的requests.Session或 Node.js的http.Agent可复用连接。批量翻译若需翻译大量文本建议按QPS分配请求间隔至少200ms一个请求并使用队列控制并发。语言代码映射建议在代码中维护一张静态映射表将通用语言标签如zh-CN、ja转换为API所需的百度系代码zh、jp。日志与监控记录每次请求的request_id、耗时、字符数及结果状态便于排查异常。字符限制检查在发送请求前在客户端校验q长度不超过5000字符避免无效调用。参考文档文本翻译API文档页原始API Markdown文档
文本翻译API的工程化集成：从参数解读到错误处理实战
发布时间：2026/7/29 8:10:53
适用场景文本翻译是许多国际化应用、内容平台、文档管理工具的基础功能。典型场景包括多语言内容生成将中文知识库自动翻译成英文、日语等用于海外文档。实时辅助翻译在IM工具或CMS中用户输入一段文本后快速返回翻译结果。本地化测试批量验证UI文本在不同语言下的显示效果。学习与实验在开发中快速处理少量文本避免每次去查词典。接口能力边界该文本翻译API支持19种语言互译包括简体中文、繁体中文、英文、日语、韩语、法语、德语、俄语、西班牙语、葡萄牙语、意大利语、荷兰语、瑞典语、丹麦语、芬兰语、波兰语、捷克语、罗马尼亚语、泰语。特别值得注意粤语yue和文言文wyw也作为独立语言代码提供。每次请求可翻译的文本最长5000字超过该长度需要自行拆分。接口的QPS限制为5次/秒超出后返回限流错误。请求参数与鉴权接口地址GET https://v1.apizero.cn/api/translateQuery参数参数名类型必填默认值说明qstring是无待翻译文本最长5000字也可用text作为别名fromstring否zh源语言代码使用百度系代码如日语jp韩语kor法语fratostring否en目标语言代码规则同上语言代码示例语言代码中文简体zh中文繁体cht粤语yue文言文wyw英文en日语jp韩语kor法语fra完整代码表请参考 官方文档。Header鉴权需要在请求头中携带Authorization或X-API-Key二选一值填写你获得的API密钥。建议使用Authorization: Bearer YOUR_API_KEY或X-API-Key: YOUR_API_KEY。curl 接入示例以下是一个完整的可复制curl命令将$APIZERO_API_KEY替换为真实密钥curl -sS \ -X GET \ -H Authorization: Bearer $APIZERO_API_KEY \ https://v1.apizero.cn/api/translate?q你好世界fromzhtoen若使用环境变量存储密钥可直接执行export APIZERO_API_KEYyour_key_here curl -sS -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/translate?q你好世界代码接入示例Python Node.jsPythonrequestsimport requests API_URL https://v1.apizero.cn/api/translate API_KEY your_key_here headers {Authorization: fBearer {API_KEY}} params { q: 你好世界, from: zh, to: en } resp requests.get(API_URL, headersheaders, paramsparams, timeout10) resp.raise_for_status() data resp.json() if data.get(code) 0: print(data[data][target_text]) else: print(Error:, data.get(msg))Node.jsaxiosconst axios require(axios); const API_URL https://v1.apizero.cn/api/translate; const API_KEY your_key_here; axios.get(API_URL, { headers: { Authorization: Bearer ${API_KEY} }, params: { q: 你好世界, from: zh, to: en }, timeout: 10000 }) .then(res { const body res.data; if (body.code 0) { console.log(body.data.target_text); } else { console.error(API错误:, body.msg); } }) .catch(err { console.error(请求失败:, err.message); });返回值解读成功时返回如下结构HTTP 200{ code: 0, msg: 成功, data: { char_count: 4, from: zh, from_name: 中文简体, source_text: 你好世界, target_text: Hello World, to: en, to_name: 英文 }, request_id: abc123 }字段类型说明codeint0 表示成功非0表示错误msgstring状态描述data.char_countint源文本字符数含空格data.fromstring源语言代码data.from_namestring源语言中文名称data.source_textstring源文本原文data.target_textstring翻译结果data.tostring目标语言代码data.to_namestring目标语言中文名称request_idstring请求唯一标识可用于日志排查常见错误码与处理HTTP状态码codemsg原因处理建议200100缺少参数q未提供待翻译文本检查请求中是否包含q或text参数200101语言代码不支持from/to使用了不支持的代码核对语言代码表使用百度系代码200102文本长度超过限制文本超过5000字拆分长文本为多次请求200103翻译失败服务端内部错误重试若持续失败联系支持401300认证失败API Key无效或缺失检查Header中是否正确附带密钥429400请求频率过高超过QPS 5次/秒加入退避重试逻辑500500服务器内部错误后端异常等待后重试注意错误响应中code字段仍在根级data可能为null。需判断code ! 0时按错误处理。工程化注意事项连接池与超时在生产环境中务必设置合理的timeout建议5-10秒并使用连接池默认Keep-Alive。Python的requests.Session或 Node.js的http.Agent可复用连接。批量翻译若需翻译大量文本建议按QPS分配请求间隔至少200ms一个请求并使用队列控制并发。语言代码映射建议在代码中维护一张静态映射表将通用语言标签如zh-CN、ja转换为API所需的百度系代码zh、jp。日志与监控记录每次请求的request_id、耗时、字符数及结果状态便于排查异常。字符限制检查在发送请求前在客户端校验q长度不超过5000字符避免无效调用。参考文档文本翻译API文档页原始API Markdown文档
