易翻译API开发者文档 | RESTful翻译接口集成指南

快速开始

完成以下三步，你就能发出第一个翻译请求。整个流程大约需要三分钟。

第一步：获取 API Key

登录易翻译API控制台，在"API密钥"页面创建一个新的密钥对。你会得到一个 Access Key ID 和一个 Secret Key。请将 Secret Key 安全保存——它只在创建时显示一次。

第二步：安装 SDK

选择你熟悉的语言，使用包管理器安装官方SDK。当然你也可以直接发送HTTP请求，但SDK会帮你处理认证签名、连接复用、错误重试等细节。

# Python (pip)
pip install traneasy-sdk

# Node.js (npm)
npm install @traneasy/sdk

# Java (Maven)
// 在 pom.xml 中添加依赖:
<dependency>
  <groupId>com.traneasy</groupId>
  <artifactId>traneasy-sdk</artifactId>
  <version>2.1.0</version>
</dependency>
            

第三步：发送第一个请求

from traneasy import Client

client = Client(
    access_key_id="te_ak_xxxxxx",
    secret_key="te_sk_xxxxxx"
)

result = client.translate(
    text="你好，世界",
    target="en"
)

print(result.translated_text)  # "Hello, world"
print(result.detected_source)  # "zh"
print(result.usage.characters)  # 4
            

认证方式

所有API请求都需要通过Bearer Token进行认证。Token通过你的Secret Key对请求参数签名生成，有效期为2小时。

生成 Bearer Token

使用SDK时，Client初始化后会自动管理Token的生成和刷新，无需手动干预。如果你直接调用HTTP接口，需要自行实现以下签名流程：

构造待签名字符串：将 HTTP Method + URI Path + Timestamp + Nonce 用换行符连接
用 Secret Key 对签名字符串做 HMAC-SHA256 哈希
将 Access Key ID、Timestamp、Nonce 和签名值组合成 Token

// 请求头示例
Authorization: Bearer te_ak_xxxxxx:1704067200:abc123def:a1b2c3d4e5f6...
Content-Type: application/json
X-Traneasy-Nonce: abc123def
            

安全提醒：不要在客户端代码（浏览器JavaScript、移动APP）中直接使用Secret Key。应当通过后端服务代理API请求，将Secret Key保存在服务器端环境变量中。前端SDK提供了无需Secret Key的受限模式，适合公开的翻译场景。

IP白名单（可选）

在控制台的"安全设置"中，你可以绑定最多20个IP地址或CIDR网段。启用后，只有来自白名单中IP的请求才会被处理。对于服务器到服务器的调用场景，建议启用此功能以增加一层保护。

错误处理

API使用标准的HTTP状态码表示请求结果。所有错误响应的Body都采用统一的JSON格式：

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API调用频率超过限制，请稍后重试",
    "request_id": "req_a1b2c3d4e5"
  }
}
            

HTTP状态码	错误码	含义
400	`invalid_request`	请求参数缺失或格式错误。检查必填字段是否都已传入，JSON格式是否正确。
401	`authentication_failed`	认证失败。Token可能已过期或签名不正确，尝试重新生成Token。
403	`ip_not_whitelisted`	当前IP不在白名单中。在控制台添加此IP或关闭IP白名单功能。
429	`rate_limit_exceeded`	超过速率限制。SDK会自动以指数退避策略重试，无需手动处理。
500	`internal_error`	服务器内部错误。这类错误极少发生，如遇到请记录request_id并联系技术支持。
503	`service_unavailable`	服务暂时不可用，通常是因为计划内维护。重试时建议间隔至少30秒。

API端点：文本翻译

这是最核心的端点，处理单条或短文本的实时翻译请求。请求在200ms内返回，适合需要即时翻译的场景。

POST /v2/translate

发送待翻译文本，指定目标语言（可选指定源语言），获取翻译结果。

参数	类型	必需	说明
text	string	是	待翻译文本，最长5000字符
target	string	是	目标语种代码，如 "en"、"ja"
source	string	否	源语种代码，不传则自动检测
domain	string	否	领域：general/legal/medical/it/finance
glossary_id	string	否	要应用的术语库ID
formality	string	否	语气：default/formal/informal

// cURL 示例
curl -X POST https://api.traneasy.com/v2/translate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "请将本文件中的技术规格翻译为英文，供海外工程师参考。",
    "target": "en",
    "domain": "it",
    "formality": "formal"
  }'

// 响应示例
{
  "translated_text": "Please translate the technical specifications"
                   " in this document into English for reference"
                   " by overseas engineers.",
  "detected_source": "zh",
  "usage": {
    "characters": 28,
    "remaining": 1950000
  },
  "request_id": "req_x7y8z9"
}
            

API端点：批量翻译

适合大批量文本的离线翻译——比如整站内容迁移、历史数据库翻译。提交后通过回调或轮询获取结果。

POST /v2/batch/translate

提交一个批量翻译任务。每个批次最多包含10万条文本。任务提交后立即返回一个Batch ID，翻译在后台异步执行。

// 提交批量任务
from traneasy import Client

client = Client(...)

batch = client.batch_translate(
    texts=["文本1", "文本2", "..."],
    source="zh",
    target="en",
    callback_url="https://your-server.com/webhook"
)

print(batch.batch_id)   // "batch_abc123"
print(batch.status)     // "queued"

// 查询任务状态
status = client.get_batch_status("batch_abc123")
print(status.progress)   // {"completed": 3200, "total": 10000}

// 任务完成后下载结果
if status.state == "completed":
    results = client.download_batch_results("batch_abc123")
    for r in results:
        print(f"{r.index}: {r.translated_text}")
            

API端点：语种列表

GET /v2/languages

获取当前API版本支持的全部语种及其代码。语种列表每月更新，新增语种会自动出现在此接口的返回结果中。

// 响应示例（部分）
{
  "languages": [
    {"code": "zh",  "name": "中文",         "native": "简体中文"},
    {"code": "en",  "name": "英语",         "native": "English"},
    {"code": "ja",  "name": "日语",         "native": "日本語"},
    {"code": "ko",  "name": "韩语",         "native": "한국어"},
    // ... 共37+语种
  ],
  "total": 37
}
            

API端点：术语库管理

术语库允许你为特定词汇指定固定的翻译。创建术语库后，在翻译请求中传入 glossary_id 即可生效。

POST /v2/glossary

创建一个新的术语库并添加初始条目。术语库创建后约30秒内生效。

// 创建术语库
glossary = client.glossary.create(
    name="游戏术语表",
    source_lang="zh",
    target_lang="en",
    entries=[
        {"source": "血条",   "target": "HP bar"},
        {"source": "暴击",   "target": "critical hit"},
        {"source": "存档",   "target": "save game"}
    ]
)

// 在翻译时引用
result = client.translate(
    text="角色暴击时血条闪烁红色",
    target="en",
    glossary_id=glossary.id
)
            

Python SDK

Python SDK 支持 Python 3.8 及以上版本，提供同步和异步两种调用方式。

# 安装
pip install traneasy-sdk

# 异步用法 (asyncio)
import asyncio
from traneasy import AsyncClient

async def main():
    async with AsyncClient(api_key="...") as client:
        tasks = [client.translate(t, target="en")
                 for t in texts]
        results = await asyncio.gather(*tasks)
    return results

asyncio.run(main())
            

JavaScript / TypeScript SDK

支持 Node.js 16+ 和现代浏览器。TypeScript 类型定义包含在包内。

// 安装
npm install @traneasy/sdk

// 使用
import { Client } from '@traneasy/sdk';

const client = new Client({
  accessKeyId: 'te_ak_xxxxxx',
  secretKey: 'te_sk_xxxxxx'
});

const result = await client.translate({
  text: '产品说明书需要翻译成日文和韩文',
  target: 'ja'
});

console.log(result.translatedText);
// "製品説明書は日本語と韓国語に翻訳する必要があります"
            

Java SDK

要求 Java 11+，基于 OkHttp 构建，支持同步和异步调用模式。

// Maven 依赖（见快速开始部分）

import com.traneasy.sdk.Client;
import com.traneasy.sdk.TranslateRequest;
import com.traneasy.sdk.TranslateResult;

public class TranslationDemo {
    public static void main(String[] args) {
        Client client = Client.builder()
            .accessKeyId("te_ak_xxxxxx")
            .secretKey("te_sk_xxxxxx")
            .build();

        TranslateResult result = client.translate(
            TranslateRequest.builder()
                .text("请确认订单中的收货地址是否正确。")
                .target("en")
                .domain("general")
                .build()
        );

        System.out.println(result.getTranslatedText());
        // "Please confirm whether the shipping
        //  address in the order is correct."
    }
}
            

常见问题

API的Base URL在不同区域有区别吗？

全球统一的Base URL是 https://api.traneasy.com/v2，我们会根据请求来源自动路由到最近的推理节点。如果你有特殊的数据驻留要求（比如数据必须保留在中国境内），可以使用中国区专属域名 https://api-cn.traneasy.com/v2，该域名下的所有请求只在中国境内的服务器处理。两个域名的API接口完全一致。

支持WebSocket或gRPC协议吗？

gRPC接口已在企业版中提供，gRPC端点地址为 grpc.api.traneasy.com:443，Proto文件可以在开发者资源页面下载。gRPC在需要持续双向流式翻译的场景下比RESTful有明显优势——比如实时会议翻译，文本是一段一段持续到达的，gRPC可以维持一条长连接持续接收和返回翻译结果。WebSocket目前不在标准支持中，如有需要可以通过私有化方案定制。

Token过期后如何处理？SDK会自动刷新吗？

是的，所有官方SDK都内置了Token的自动刷新机制。当你初始化Client时传入Access Key和Secret Key后，SDK会在Token过期前主动刷新，你不需要编写任何Token管理代码。如果使用原生的HTTP客户端直接调用API，你需要自己实现签名和刷新逻辑——这也是我们推荐使用SDK的一个重要原因。

API的版本策略是怎样的？旧版本会废弃吗？

当前主版本是v2（自2023年3月起）。当我们需要引入不兼容的变更时，会发布新的主版本号（如v3），并至少保留旧版本12个月的过渡期。过渡期内旧版本仍可正常使用，我们会通过邮件和控制台消息通知所有API用户迁移。补丁级别的更新（如新增可选参数、优化翻译质量）不会变更版本号，直接上线。

可以在前端（浏览器）直接调用翻译API吗？

技术上可以，但不推荐用于生产环境。浏览器端调用翻译API意味着你的Secret Key会暴露在前端代码中——任何人打开开发者工具都可以获取到它。正确的做法是通过你的后端服务代理API请求：前端将待翻译文本发送给你的后端，后端携带Secret Key调用易翻译API，然后将结果返回给前端。如果你必须在前端使用，JavaScript SDK提供了一个Public模式——不传入Secret Key，仅传入Access Key，但这种方式有更低的速率限制和更严格的CORS策略。

如何调试API调用中的问题？

每个API响应中都包含一个 request_id 字段——这是排查问题时最重要的线索。遇到错误时，记录这个ID并在技术支持工单中提供，我们的工程师可以通过它追溯到这次请求的完整处理链路。此外，在SDK初始化时可以设置 debug=True（Python）或 logLevel: 'debug'（JS），SDK会输出详细的请求和响应日志，包括签名过程、重试次数和延迟数据。

支持哪些内容类型的翻译？纯文本以外的格式呢？

翻译API端点（/v2/translate）接受纯文本和HTML两种输入类型。如果你传入HTML，API会识别并保留HTML标签结构，只翻译标签之间的文本内容。Markdown也受支持——代码块、链接URL等不会被翻译。对于完整的文件格式（PDF、Word、Excel等），请使用文档翻译接口（/v2/document/translate），它是独立的端点，返回的是翻译后的文件下载链接，而非文本。

易翻译 REST API v2

快速开始

第一步：获取 API Key

第二步：安装 SDK

第三步：发送第一个请求

认证方式

生成 Bearer Token

IP白名单（可选）

错误处理

API端点：文本翻译

API端点：批量翻译

API端点：语种列表

API端点：术语库管理

Python SDK

JavaScript / TypeScript SDK

Java SDK

常见问题

API的Base URL在不同区域有区别吗？

支持WebSocket或gRPC协议吗？

Token过期后如何处理？SDK会自动刷新吗？

API的版本策略是怎样的？旧版本会废弃吗？

可以在前端（浏览器）直接调用翻译API吗？

如何调试API调用中的问题？

支持哪些内容类型的翻译？纯文本以外的格式呢？