<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 文本翻译

> 对接腾讯云 TMT（机器翻译）通用版，支持 18 种语言互译，自动检测源语言。

• **18 种语言**：中文 / 繁体中文 / 英文 / 日语 / 韩语 / 法语 / 西语 / 意语 / 德语 / 土语 / 俄语 / 葡语 / 越南语 / 印尼语 / 泰语 / 马来语 / 阿拉伯语 / 印地语
• **多种参数形式**：from/to 同时支持中文名（「英文」）和语言代码（「en」），auto / 自动检测 / 自动 / 空字符串均视为自动
• **检测增强**：auto 模式下额外返回 detected_language（如 fr）+ detected_name（如 法语），便于前端展示「检测到法语」
• **缓存命中提速**：相同文本+方向 24h 缓存（按 sha256 哈希），命中只需 ~150ms 不计入上游配额
• **错误码细分**：上游 InvalidParameter / TextTooLong / 不支持语种 等映射为 4000 客户端错误，便于前端区分提示

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `translate` |
| 接口名称 | 文本翻译 |
| 接口地址 | `https://v1.apizero.cn/api/translate` |
| 请求方法 | `POST` |
| 分类 | ai |
| 提供方 | 腾讯云 TMT |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 5 req/s |
| 每日免费额度 | 50 次（已认证用户） |
| 匿名每日额度 | 20 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名每日 20 次、QPS 2；登录用户每日 50 次、QPS 5（全部免费）。命中 24h 缓存不计入上游配额。\n\n支持的语言代码：zh（中文）、zh-TW（繁体中文）、en（英文）、ja（日语）、ko（韩语）、fr（法语）、es（西班牙语）、it（意大利语）、de（德语）、tr（土耳其语）、ru（俄语）、pt（葡萄牙语）、vi（越南语）、id（印尼语）、th（泰语）、ms（马来语）、ar（阿拉伯语）、hi（印地语）。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `text` | `string` | 是 | 待翻译文本，1-5000 字符（中英文均按 1 字符计） | `Hello, how are you?` |
| `from` | `string` | 否 | 源语言。中文名（如「英文」）或代码（如「en」），auto / 自动检测 / 空字符串均视为自动检测。默认 auto | `auto` |
| `to` | `string` | 否 | 目标语言。中文名或代码，必须明确指定（不能是 auto）。默认 en（英文） | `zh` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | API Key 鉴权头，格式 Bearer sk_live_xxx；匿名调用时可省略（每日 20 次免费） | `Bearer sk_live_xxxxxxxxxxxxxx` |
| `Content-Type` | `string` | 否 | 支持 application/x-www-form-urlencoded 或 application/json | `application/json` |

## 5. 请求示例 (cURL)

```bash
curl -X POST "https://v1.apizero.cn/api/translate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Hello, how are you?",
  "from": "auto",
  "to": "zh"
}'
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `source_text` | `string` | 原文（回传 text 参数） | — |
| `target_text` | `string` | 译文 | — |
| `from` | `string` | 解析后的源语言代码（如 auto / en / zh / ja） | — |
| `to` | `string` | 解析后的目标语言代码 | — |
| `from_name` | `string` | 源语言中文名（如 自动检测 / 英文 / 中文） | — |
| `to_name` | `string` | 目标语言中文名 | — |
| `detected_language` | `string` | 腾讯云实际检测到的源语言代码；非 auto 模式下与 from 相同 | — |
| `detected_name` | `string` | 检测到的源语言中文名（auto 模式下用于前端展示「检测到 XX」） | — |
| `char_count` | `number` | 本次翻译字符数（腾讯云 UsedAmount，便于配额预估） | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "source_text": "Hello, how are you?",
        "target_text": "你好,你好吗?",
        "from": "auto",
        "to": "zh",
        "from_name": "自动检测",
        "to_name": "中文",
        "detected_language": "en",
        "detected_name": "英文",
        "char_count": 19
    },
    "request_id": "abc123def456"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数错误：text 为空 / 超 5000 字 / 不支持的源或目标语言 / 源目标语言相同 / 上游 InvalidParameter / TextTooLong |
| `4015` | `—` | 匿名调用每日额度用完，需要 API Key |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |
| `5000` | `—` | 内部错误：腾讯云 SecretId/Key 未配置（联系平台管理员） |
| `5020` | `—` | 上游 HTTP 失败 |
| `5021` | `—` | 上游响应格式异常 / 翻译服务暂不可用 |

## 9. 变更日志

- **1.0.0** (2026-05-07)
  - 首次上线，对接腾讯云 TMT 通用版机器翻译
  - 支持 18 种语言互译 + auto 自动检测
  - from/to 双形式：中文名（如「英文」）或代码（如「en」）均可
  - 安全增强：腾讯云 SecretId/Key 通过 .env 注入，避免代码仓库泄露
  - 新增 detected_language / detected_name 字段，auto 模式下展示真实识别语言
  - 新增 char_count 字段（腾讯云 UsedAmount），便于配额预估
  - 错误细分：InvalidParameter / TextTooLong 等上游 4xx 错误映射为 4000，与 5xx 上游故障区分
  - 同源/目标语言互译直接拦截 4000，不浪费上游配额
  - sha256 哈希缓存 24h，命中提速 ~80%
  - 支持 application/json 请求体（v1 网关 mergeJsonBody 自动解析）

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/translate`

Source: `https://apizero.cn/aidocs/translate/raw.md`
Last updated: 2026-05-11T16:16:07+08:00