#云上曲率对接文档

#文档说明

• 文档用途：整理云上曲率审核服务对接接口，供后端配置、联调和问题排查使用。
• 当前进度：第一组，文字审核接口。
• 整理日期：2026-06-03。
• 整理依据：用户提供的接口截图，以及云上曲率官方文档页面。
• 官方文档：
  • 文字审核异步检测任务提交
  • 文字审核异步检测结果回调接口规范

说明：本项目后续共有 4 组云上曲率接口文档内容。本文档当前仅整理第一组“文字审核”，其余接口待后续图片补充后继续追加。

#一、文字审核

#1.1 异步检测任务提交

#接口信息

项目	内容
请求 URL	https://tsafe.ilivedata.com/api/v1/text/async/check/submit
请求方法	POST
请求体格式	application/json;charset=UTF-8
响应格式	application/json;charset=UTF-8
认证方式	请求头签名

#请求 Header

Header	必填	说明
Content-Type	是	固定值：application/json;charset=UTF-8
Accept	是	固定值：application/json;charset=UTF-8
X-AppId	是	项目的唯一标识，取自云上曲率控制台“服务配置”中的项目编号
X-TimeStamp	是	请求 UTC 时间戳，按 W3C 标准格式化，例如：2010-01-31T23:59:59Z
Authorization	是	签名值

#请求参数

参数	必填	类型	说明
content	是	String	待检测文本，UTF-8 编码，长度不超过 2048 个字符
strategyId	否	String	策略编号，不传时使用默认策略 DEFAULT
country	否	String	国家代码，不传时使用默认配置
userId	否	String	终端用户唯一 ID，长度不超过 64 个字符
sessionId	否	String	用户会话 ID，长度不超过 64 个字符
receiverId	否	String	接收者 ID，长度不超过 64 个字符
userName	否	String	用户名、昵称，长度不超过 32 个字符
userLevel	否	Number	用户等级
totalPay	否	Number	用户充值金额，最多支持小数点后 2 位
registrationDate	否	Number	用户注册时间，10 位秒级时间戳
msgCount	否	Number	消息发送次数
msgType	否	String	消息类型
pkgChannel	否	String	安装包渠道
userIp	否	String	用户 IP 地址
did	否	String	用户设备 ID
dtype	否	String	用户设备类型：1 iPhone，2 Android，3 iPad，4 Windows Phone，5 PC，6 Web，7 WAP
extra	否	Map	其他业务透传内容，可传多个 key/value，例如：{"server":"123","version":"456"}
checkTags	否	Array	指定检测一级类别，支持：100 涉政，110 暴恐，120 违禁，130 色情，150 广告，160 辱骂，170 仇恨言论，180 未成年保护，190 敏感热点，220 私人交易，410 违规表情，420 昵称相关，999 自定义
callbackUrl	否	String	回调地址。不推荐每次请求传入，建议在控制台统一配置回调地址和密钥
callbackSecretKey	否	String	回调密钥。不推荐每次请求传入，建议在控制台统一配置回调地址和密钥

#请求示例

{
  "content": "fuck you",
  "userId": "1234556",
  "strategyId": "123"
}

指定检测类别示例：

{
  "content": "fuck you",
  "userId": "12345678",
  "checkTags": [150, 160]
}

#请求签名

云上曲率使用 appId 和 secretKey 对请求做签名。服务端收到请求后会使用相同算法验证签名，签名不一致时返回 401。

签名计算步骤：

1. 将请求体 JSON 字符串按 UTF-8 编码后做 SHA-256，结果转换为 16 进制字符串，不是 Base64。

CanonicalizedQueryString = hex(sha256(jsonBody))

2. 构造待签名字符串。\n 表示 ASCII 换行符。

StringToSign =
HTTPMethod + "\n" +
HostHeaderInLowercase + "\n" +
HTTPRequestURI + "\n" +
CanonicalizedQueryString + "\n" +
"X-AppId:" + SAME_APPID_IN_HEADER + "\n" +
"X-TimeStamp:" + SAME_TIMESTAMP_IN_HEADER

3. 使用 secretKey 作为密钥，对 StringToSign 执行 HMAC-SHA256。

4. 将 HMAC 结果转换为 Base64 字符串。

5. 将 Base64 字符串放入请求头 Authorization。

Authorization: <signature>

签名字段约束：

字段	说明
HTTPMethod	本接口固定为 POST
HostHeaderInLowercase	固定为 tsafe.ilivedata.com
HTTPRequestURI	请求 URI 的绝对路径，不包含 query string；本异步提交接口为 /api/v1/text/async/check/submit
X-AppId	必须与请求头中的 X-AppId 完全一致
X-TimeStamp	必须与请求头中的 X-TimeStamp 完全一致

风险提醒：官方文档截图中的签名示例使用了 /api/v1/text/check，该路径是同步单条检测路径；文字异步提交接口实际 URL 是 /api/v1/text/async/check/submit。后端接入时应以实际请求路径参与签名，并在联调阶段确认云上曲率服务端验签行为。

#响应参数

字段	类型	说明
errorCode	Number	错误码，0 表示成功
errorMessage	String	错误消息，成功时可能省略
taskId	String	任务唯一标识，用于区分不同调用和匹配异步回调结果

#响应示例

{
  "errorCode": 0,
  "taskId": "us_**************************"
}

#错误码

HTTP 状态码	错误码	错误消息	错误原因
200	0	此字段省略	请求成功
429	1104	Out of Rate Limit	请求频率超过限制，20 条/秒；或请求文本字符总数超过频率限制，长度超过 100 的字符总数限制为 1K 字符/秒
405	1004	Method Not Allowed	HTTP method 不符合接口要求
411	1007	Not Content Length	POST 请求头未设置正确的 content-length
400	1002	API Not Found	根据 HTTP 请求 path 没有找到对应 API
400	1003	Bad Request	请求解析失败
400	2000	Missing Parameter	JSON 缺少参数 content
400	2102	Input Too Long	JSON 参数 content 长度超过限制
401	1102	Unauthorized Client	参数 X-AppId 无效
401	1106	Missing Access Token	没有 Authorization
401	1107	Invalid Token	Authorization 不正确
401	1108	Expired Token	X-TimeStamp 过期
401	2000	Missing Parameter	缺少 X-TimeStamp
401	2001	Invalid Parameter	X-TimeStamp 格式错误

#1.2 异步检测结果回调

#回调说明

云上曲率会针对 .../async/check/submit 异步任务，将审核结果按 taskId 维度推送到客户方回调接口。

回调配置方式：

方式	说明
控制台配置	在云上曲率控制台“服务配置”中配置回调 URL、回调区域，回调密钥由控制台生成
提交任务时传参	在异步检测任务提交接口中传入 callbackUrl 和 callbackSecretKey

注意事项：

• 提交任务时传入的回调参数优先级高于控制台配置。
• 如果提交任务时使用接口入参方式，必须保证 callbackUrl 和 callbackSecretKey 均不为空，否则回调不生效。
• 客户方需要保证回调接收接口稳定可用。
• 云上曲率在收到客户方响应后，如果不符合成功规范，则认为推送失败；失败后间隔 10 秒重试，最多推送 3 次；第 3 次仍失败后不再继续推送，需要通过主动查询结果接口获取结果。

#回调鉴权

客户方使用配置回调参数后分配的密钥校验回调请求。

签名算法：

1. 将收到的请求体参数按 ASCII 码升序排序，不包含 signature 参数。
2. 将排序后的参数按 key + value 方式拼接成字符串。
3. 将回调密钥追加到第 2 步生成的字符串末尾。
4. 将第 3 步生成的字符串按 UTF-8 编码后执行 MD5，得到 signature。
5. 云上曲率会将 signature 放入请求 Header，客户方接收回调时需要按相同规则计算并比对。

Java 示例：

/**
 * 生成签名。
 *
 * @param secretKey 后台密钥
 * @param params 接口请求参数名和参数值 map，不包括 signature 参数名
 * @return signature
 */
public static String signature(String secretKey, Map<String, String> params) {
    String[] keys = params.keySet().toArray(new String[0]);
    Arrays.sort(keys);

    StringBuilder signBuilder = new StringBuilder();
    for (String key : keys) {
        signBuilder.append(key).append(params.get(key));
    }
    signBuilder.append(secretKey);

    try {
        return DigestUtils.md5Hex(signBuilder.toString().getBytes("UTF-8"));
    } catch (UnsupportedEncodingException e) {
        // error
    }
    return null;
}

#请求地址及方式

名称	值
callbackUrl	客户方提供的回调地址，HTTP 协议
HTTP_METHOD	POST

#请求 Header

Header	类型	必填	说明
Content-Type	String	是	固定值：application/json
signature	String	是	签名，用于验证回调请求合法性

#请求参数

参数	类型	说明
appId	String	所属项目编号
taskId	String	提交异步审核时返回的任务 ID
result	JSON String	审核结果，字符串内容为 JSON

#result 字段结构

字段	类型	说明
code	Number	预留字段，业务侧可忽略
textSpam	TextSpam	文本审核结果信息
warning	Boolean	自定义广告词的报警信息，在控制台添加黑名单时配置
taskId	String	区分不同次调用的唯一标识
language	String	语种
startTime	Number	时间戳，代表检测文本调用时间
endTime	Number	时间戳，代表检测文本结果返回时间

#TextSpam

字段	类型	说明
content	String	检测完成后，如果含有敏感词，敏感词会变星，其他内容正常返回
result	Number	审核结论：0 通过，1 建议审核，2 不通过
tags	List	分类信息
wordList	String[]	敏感词列表

#Tag

字段	类型	说明
tag	Number	一级分类信息代码：100 涉政，110 暴恐，120 违禁，130 色情，150 广告，160 辱骂，170 仇恨言论，180 未成年保护，190 敏感热点，220 私人交易，300 广告法，410 违规表情，420 昵称，900 其他，999 用户自定义类
tagName	String	检测文本命中的一级类型名称
tagNameEn	String	检测文本命中的一级类型名称，英文
level	Number	分类级别：0 正常，1 疑似，2 异常
confidence	Number	置信度，0 到 100 之间；数值越大，表示检测文本为广告的可能性越大。仅 tag=150 时返回
subTags	List	敏感信息的二级分类

#SubTag

字段	类型	说明
subTag	Number	二级分类编码，具体取值参考云上曲率分类编码对照表
subTagName	String	检测文本命中的二级类型名称
subTagNameEn	String	检测文本命中的二级类型名称，英文
wordList	String[]	命中详情

#客户方响应

客户接口接收到回调结果后，需要返回 JSON 应答。接口响应 code 为 0 表示此次回调成功；回调处理异常时，应返回 code=500 或 HTTP 4xx。

字段	类型	必填	说明
code	Number	是	应答 code，0 表示此次回调成功
message	String	否	具体描述信息

成功响应示例：

{
  "code": 0,
  "message": "success"
}

异常响应示例：

{
  "code": 500,
  "message": "callback handle failed"
}

#1.3 后端接入注意事项

• taskId 是异步提交和回调结果关联的关键字段，后端落库时应按 taskId 做幂等处理，避免云上曲率重试回调导致重复写入。
• 回调处理应先验签，再解析 result JSON 字符串，验签失败不得写入审核结果。
• 回调接口需要快速响应，复杂后置处理建议投递队列异步执行，避免回调请求超时后触发重复推送。
• 本项目按严格前置机审处理 textSpam.result 等审核结论：只有 0 明确通过才允许业务生效；1 建议审核、缺少结论或未知值均记为机审失败并阻断业务；2 记为机审拒绝并直接拦截。
• content、命中词和用户昵称等字段可能包含敏感内容，日志中不应明文记录完整文本；如需排查，建议记录 taskId、用户 ID、结果码、分类码和文本摘要哈希。
• 云上曲率请求频率限制为 20 条/秒，且长文本有总字符频率限制；高并发场景建议通过队列限速提交审核任务。