文本翻译-V3

一、服务概述

云上曲率翻译开放平台是面向游戏行业广大开发者提供开放服务的平台。

二、服务申请

翻译 API 采用全流程自助申请的模式。

点击云上曲率官网(https://www.ilivedata.com/) 右上方的“免费试用”按钮，按照提示信息“注册账号-创建企业”后，在控制台选择“实时文本翻译”服务并创建应用，即可获得 pid 和服务密钥。

如需开通更多服务，可在管理控制台-总览页面开通其他服务。

三、接入方式

请求 URL: https://translate.ilivedata.com/api/v3/translate
请求方法: HTTP POST
请求 Header:

参数	是否必需	值	描述
Content-Type	必需	application/json;charset=UTF-8	请求体类型
Accept	必需	application/json;charset=UTF-8	接受的返回类型
X-AppId	必需	项目唯一标识	获取方式: <控制台-服务配置>中的项目编号
X-TimeStamp	必需	当前时间	需要把当前时间戳按W3C标准格式化，例如: 2010-01-31T23:59:59Z. (http://www.w3.org/TR/xmlschema-2/#dateTime)
Authorization	必需	签名字符串	计算方式参照下方的请求签名

请求体JSON参数

参数	是否必传	描述
q	必传	需要翻译的原文文本。文本为不超过 1024 个字符的 UTF-8 编码字符串
source	可选	原文本的语种（下称“源语言”）。可设置为语言支持中列举的 ISO 639-1 标准的语言代码之一。未传该参数及 `source` 值为空或无效时，将自动进行语种检测。
target	必传	翻译的目标语言，同上需设置为语言支持文档中列举的 ISO 639-1 标准的语言代码之一。
suggestedSource	可选	回退参考语种。自动语种检测失败时，可将该语种作为源语言。同上需设置为语言支持文档中列举的 ISO 639-1 标准的语言代码之一。
profanity	可选	敏感内容过滤功能。可选值为 `censor` 或 `off` ，分别对应开启和关闭，如未指定则默认关闭。此功能仅通过关键词屏蔽，如果您的业务对文本审核有更高要求或需定制，欢迎您接入云上曲率的多语言文本审核服务。
fromId	可选	需要翻译的文本的发送人id，使用上下文翻译模型时，需要传此参数。
toId	可选	需要翻译的文本的接收人id
precedingContext	可选	需要翻译的文本的上文信息，为json对象列表。使用上下文翻译模型时需要传此参数。对象包含两个字段：userId（用户id）和text（任意语种的上文文本），传入方式：“precedingContext” : [{“userId”: “user1”,“text”:“123”}, {“userId”: “user2”,“text”:“456”}]

请求签名:

当用户请求 Translation API 时，可以使用 appId 和 secretKey 对请求做签名，当 API 收到带签名信息的请求之后，将使用相同的算法验证签名，如果发现签名不一致，API 将会返回 401 给用户。如果 API 验证签名一致，且 appId 对应的用户有权限操作请求的资源，则请求成功，否则 API 返回 401。

通过 HTTP 请求 Header 发送签名

方法: 在请求中加入名为 Authorization 的 Header，值为签名值。如下：

	Authorization: *****

签名计算方法
1. 构造规范化的请求字符串（Canonicalized Query String）:
  
  将请求体JSON字符串以UTF-8字符编码做sha256编码后转换为16进制字符串（注意不是Base64） CanonicalizedQueryString = hex(sha256(jsonBody))
2. 构造被签名字符串 StringToSign ("\n" 代表 ASCII 里的换行符):
```
StringToSign = HTTPMethod + "\n" + 
               HostInLowercase + "\n" + 
               HTTPRequestURI + "\n" + 
               CanonicalizedQueryString <从上一步得到> + "\n" +
               "X-AppId:" + SAME_APPID_IN_HEADER + "\n" +
               "X-TimeStamp:" + SAME_TIMESTAMP_IN_HEADER
```
  HTTPRequestURI 是请求 URI 的绝对路径，不包含请求串。如果 HTTPRequestURI 为空，也需保留一个正斜杠 /。
  
  使用 HMAC-SHA256 协议创建基于哈希的消息身份验证代码（HMAC），然后计算签名。
3. StringToSign 作为签名字符串，secretKey 作为秘钥，SHA256作为哈希算法
  
  有关 HMAC 的更多信息，请参阅 HMAC：用于消息身份验证的哈希密钥（https://tools.ietf.org/html/rfc2104）。
4. 将上一步的结果转换为 BASE64 串
5. 将 BASE64 串放入 HTTP 请求 Header 的 Authorization
签名示例

下面是 appId & secretKey 的示例

 appId=999
 secrectKey=HSA3R+UQYYasWX1ZLrxzDTZxjrMW1ghD6DBbC4gnIjs=

下面是示例请求

Request Json:

{"q": "hello world", "target": "zh-CN", "fromId": "user1", "precedingContext": [{"userId": "user1", "text": "123"}, {"userId": "user2", "text": "456"}]}

生成CanonicalizedQueryString： b79fac47c8936c61bb90fa4f70babb4d62feb196cf741d22ce02751a5bb47d53

生成 StringToSign

POST\n
translate.ilivedata.com\n
/api/v3/translate\n
b79fac47c8936c61bb90fa4f70babb4d62feb196cf741d22ce02751a5bb47d53\n
X-AppId:999\n
X-TimeStamp:2024-09-06T11:46:26Z

HMAC 计算得到的签名

f1O6j0cXEKkhKQji43p+/uMQSDAX9ht2LrbTLQ08kSQ=

HTTP 响应:

Content-Type: application/json;charset=UTF-8

结果为JSON格式，具体参数说明：

字段名	类型	描述
errorCode	Number	错误码，0表示成功
errorMessage	String	错误消息
translation	对象	翻译结果

translation结构：

字段名	类型	描述
source	String	原文语种
target	String	翻译目标语种
sourceText	String	原文文本
targetText	String	翻译结果

HTTP响应示例:

          {
             "errorCode": 0,
             "translation": {
                "source": "en",
                "target": "zh-CN",
                "sourceText": "hello world",
                "targetText": "你好世界"
             }
          }

文本翻译-V3

一、 服务概述

二、 服务申请

三、 接入方式

一、服务概述

二、服务申请

三、接入方式