1. 适用场景在全球化应用、跨境电商、内容平台或社交媒体中文本翻译是最常见的基础能力之一。典型的真实业务场景包括商品标题批量翻译跨境商品管理后台中批量将商品名称从中文翻译为英文、日文等降低人工维护复杂度。古文/方言内容处理教育或文化类应用需要将文言文、粤语等特殊文本翻译为现代中文或英文。多语言内容审核对非中文内容先翻译再进行关键词过滤或敏感词检测。这些场景对翻译接口的延迟、准确性、语言覆盖范围以及调用维护复杂度都有较高要求。下面介绍的文本翻译 API 支持 19 种语言互译包括粤语和文言文可满足大部分中小规模翻译需求。2. 接口能力边界维度说明接口路径GET https://v1.apizero.cn/api/translateQPS 限制5 次/秒超出可能返回 429 状态码单次最大字长5000 字符q参数语言支持19 种语言互译含粤语yue、文言文wyw等语言代码采用百度系标准鉴权方式HeaderX-API-Key或Authorization根据实际文档响应格式JSON 数组内嵌code、data、msg等字段注意语言代码请使用百度翻译代号例如日语为jp、韩语为kor、法语为fra、英语为en、中文简体为zh。完整对照表可参考官方文档。3. 请求参数与鉴权3.1 Query 参数参数必填类型默认值说明示例q是string无待翻译文本最长 5000 字符兼容text参数名你好世界from否stringzh源语言代码zhto否stringen目标语言代码en3.2 Header 鉴权每次请求必须在 HTTP 头部携带 API KeyX-API-Key: YOUR_API_KEY其中YOUR_API_KEY替换为从平台获取的密钥。若使用Authorization头部请参照文档确认格式。4. curl 请求示例以下示例将中文短语 “Hello World 的中文” 翻译为英文默认fromzh、toen。curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/translate?q你好世界若需要指定语言例如将日语 “こんにちは” 翻译为中文简体curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/translate?qこんにちはfromjptozh注意请确保q参数已进行 URL 编码尤其是包含中文、特殊字符时。curl 的--data-urlencode选项可用于自动编码。5. 代码接入示例5.1 Pythonrequests 库import requests API_KEY your_api_key_here url https://v1.apizero.cn/api/translate params { q: 在全球化时代翻译能力不可或缺。, from: zh, to: en } headers { X-API-Key: API_KEY } resp requests.get(url, paramsparams, headersheaders) if resp.status_code 200: data resp.json() # 注意响应为 JSON 数组取第一个元素 if isinstance(data, list) and len(data) 0: result data[0].get(example, {}) print(翻译结果, result.get(data, {}).get(target_text)) else: print(异常响应, data) else: print(HTTP 错误, resp.status_code)5.2 JavaScriptfetchconst API_KEY your_api_key_here; const url new URL(https://v1.apizero.cn/api/translate); url.searchParams.set(q, JavaScript 是 Web 开发的核心语言); url.searchParams.set(from, zh); url.searchParams.set(to, en); fetch(url, { method: GET, headers: { X-API-Key: API_KEY } }) .then(res res.json()) .then(data { // 响应为数组第一项为成功响应 const example Array.isArray(data) ? data[0].example : data; console.log(翻译结果, example.data.target_text); }) .catch(err console.error(请求失败, err));6. 返回字段解读成功时 HTTP 状态码为 200响应体为一个 JSON 数组每个元素包含content_type、description、example和status。其中example内部结构如下字段类型说明codeint业务状态码0 表示成功msgstring状态描述成功时为“成功”request_idstring请求唯一标识便于排查dataobject翻译结果数据data.char_countint源文本字符数不含空格data.fromstring源语言代码data.from_namestring源语言中文名称data.source_textstring原文data.target_textstring翻译结果data.tostring目标语言代码data.to_namestring目标语言中文名称示例返回[ { content_type: application/json, description: 成功, example: { code: 0, data: { char_count: 4, from: zh, from_name: 中文简体, source_text: 你好世界, target_text: Hello World, to: en, to_name: 英文 }, msg: 成功, request_id: abc123 }, status: 200 } ]7. 常见错误及处理现象可能原因处理建议HTTP 400q参数缺失或超过 5000 字符检查请求参数长度对长文本分片HTTP 401 / 403API Key 无效、过期或未携带确认X-API-Key头部正确且密钥有效HTTP 429请求超过 QPS 限制5次/秒加入退避重试逻辑如指数退避HTTP 500服务端内部错误等待后重试保留request_id反馈返回code ! 0业务错误详见msg字段根据msg提示修正参数8. 工程化注意事项QPS 控制接口限制 5 QPS建议在客户端做限流如使用令牌桶或带延迟的排队请求。若需批量翻译大量文本可将任务分成多批每批间隔至少 200ms。字符数监控单次请求q不能超过 5000 字符。对于长篇内容需先拆分如按段落或句子再分别请求。注意中文字符每个算一个字符英文单词中的空格也计数。语言代码统一项目内部定义语言代码常量表避免拼写错误如日语jp而非ja。建议将代码映射到枚举或配置文件。幂等性与重试翻译请求本身是幂等的相同输入-相同输出但网络波动可能导致超时。建议在重试时使用指数退避并限制最大重试次数如3次。响应解析健壮性响应可能因网络问题而异常务必try-catch捕获 JSON 解析错误。同时检查返回的code是否为 0而非仅依赖 HTTP 状态码。日志记录记录每次请求的request_id、char_count以及耗时便于后续排查问题和维护复杂度分析。隐私与合规若翻译内容涉及用户隐私如聊天记录需确保传输使用 HTTPS且不在日志中明文记录原文可记录脱敏版本。9. 参考文档官方文档https://apizero.cn/aidocs/translate原始 Markdownhttps://apizero.cn/aidocs/translate/raw.md语言代码表请参见文档中的附录部分。