翻译

鉴权

具体验签过程参考 服务端回调验签机制。 sign 字段的签算过程见 s2s md5 加密 小节。

接口

1. 流式（SSE）翻译接口

POST /api/open/translate/v2/text/sse

1.1. 注意点

• 有共享资源池使用限制，大量使用请提前联系我们准备资源
• 接口返回值内容是 SSE 事件流，请使用 SSE 接收数据

1.2. 请求

请求格式 application/json

1.2.1. Request Body

参数名	类型	必填	说明
text	String	✅	待翻译文本
targetLanguage	String	✅	目标语言，ISO 639 语言代码，参考 Google 翻译支持的语言
appId	Integer	✅	应用 ID
nonce	String	✅	随机字符串，用于防重放攻击
timestamp	Long	✅	Unix 时间戳（秒级）
sign	String	✅	请求签名
xdid	String	✅	用户 ID
roleId	String	✅	角色 ID

示例

{
    "text": "string",
    "targetLanguage": "string",
    "xdid": "string",
    "roleId": "string",
    "appId": 0,
    "nonce": "string",
    "timestamp": 0,
    "sign": "string"
}

1.3. 响应 (SSE)

响应格式 `text/event-stream`:
event: chunk
data:{"chunk":"翻译"}

event: chunk
data:{"chunk":"内容"}

回撤之前发布的所有内容
event: retract
data:{}

event: error
data:{"error":"错误"}

结束标志
event: done 
data:{"isDone":true}

1.3.1 响应流事件类型

只以 done 事件为结束标识，即使收到 error 也以 done 事件为结束标志。

Event 类型	Data 格式 （ json 对象）	说明
chunk	{"chunk":"翻译内容片段"}	翻译内容分块推送
error	{"error":"错误"}	错误
retract	{}	回撤之前发布的所有内容
done	{"isDone":true}	翻译完成标识

1.4. 请求示例代码

curl --location --request POST '/api/open/translate/v2/text/sse' \
--header 'Content-Type: application/json' \
--data-raw '{
    "text": "string",
    "targetLanguage": "string",
    "xdid": "string",
    "roleId": "string",
    "appId": 0,
    "nonce": "string",
    "timestamp": 0,
    "sign": "string"
}'

2. 传统翻译接口（不推荐）

POST /api/open/translate/text

2.1. 特点

• 底层是谷歌翻译
• 翻译速度稳定，千字长文也能在秒内返回结果
• 成本高、翻译结果质量一般

2.2. 请求

Body 请求参数

{
  "text": "string",
  "targetLanguage": "string",
  "appId": 0,
  "nonce": "string",
  "timestamp": 0,
  "sign": "string"
}

2.2.1. 请求参数

名称	位置	类型	必选	说明
body	body	Request	否	none

返回示例

200 Response

"string"

2.2.2. 返回结果

状态码	状态码含义	说明	数据模型
200	OK	none	Response

2.3. 数据模型

2.3.1. Request

{
  "text": "string",
  "targetLanguage": "string",
  "appId": 0,
  "nonce": "string",
  "timestamp": 0,
  "sign": "string"
}

2.3.2. Request 属性

名称	类型	必选	约束	中文名	说明
text	string	true	none		none
targetLanguage	string	true	none		ISO_639 https://cloud.google.com/translate/docs/languages
appId	integer	true	none		none
nonce	string	true	none		none
timestamp	integer(int64)	true	none		none
sign	string	true	none		none

2.3.3. Response

{
  "translate": "string"
}

2.3.4. Response 属性

名称	类型	必选	约束	中文名	说明
translate	string	false	none		none

3. 业务异常

错误信息	说明
翻译内容不能为空	text 为空或仅包含空白字符
目标语言不能为空	targetLanguage 为空
翻译内容不能超过 500 个字符	文本超出长度限制
illegal params	缺少必要的签名参数
timestamp expired	时间戳过期
sign error	签名校验失败
Service unavailable	服务熔断中