跳到主要内容

声网语音流异步接口

1. 接口介绍

声网客户使用 云端录制 服务时,可选择图普的语音流识别作为扩展服务,对录制中的语音进行实时审核。通过云端录制进行审核时,声网会将录制的数据源整合为 RTMP 流,图普根据声网提供的流地址进行拉流切片审核,并将审核结果回调给客户。 目前图普语音流识别已支持声网单流录制 & 合流录制。业务流程如下:

说明:A 序列为客户与声网之间的交互,B 序列为声网与图普之间的交互,C 序列为图普与客户之间的交互。

提示
  1. 异步文件接口对文件大小和时长没有限制,根据最佳实践,建议文件大小小于 10 GB;异步流接口对流的时长没有限制,建议客户在流关闭时主动调用任务关闭接口。

  2. 图普采用 任务并发数 对异步接口进行并发控制,即任一时刻最多允许 N 个任务同时处理。在测试期间,任务并发数为 30(允许同时处理 30 个任务),正式使用或需要增加时请联系客户经理调整。当超出任务并发数后继续提交任务时,根据接口类型略有不同:

    • 异步文件接口:可以正常提交任务,提交的任务排队等待处理;
    • 异步流接口:提交任务时返回超出并发状态码(由于流的实时性要求,无法排队等待处理,因此无法继续提交)。

参考文档

下面列出声网关于 云端录制 相关的文档:

2. 请求

客户通过调用声网 开始云端录制接口 ,开始进行云端录制。调用时,在 clientRequest.extensionServiceConfig 中指定图普语音流识别相关参数。该参数说明摘录如下(请以声网文档页面说明为准):


extensionServiceConfig 是一个 JSON Object,用于设置扩展服务。扩展服务是基于声网 RTC SDK 的一系列应用服务,能够对声网 RTC SDK 中产生的音视频流进行进一步处理,如页面录制、视频点播服务、智能语音审核服务。

extensionServiceConfig 包含以下字段:

  • errorHandlePolicy:(选填)String 类型。错误处理策略。目前仅可设置为默认值 error_abort,表示当某一扩展服务发生错误后,订阅及其他非扩展服务均停止。
  • apiVersion:(选填)String 类型,云端录制 RESTful API 的版本号,默认为 v1
  • extensionServices:JSONArray 类型,由每个扩展服务的设置组成的数组。

2.1 扩展服务参数说明

参数名称类型是否必填说明
serviceNameString扩展服务的名称,需填入 tupu_voice_scan
errorHandlePolicyString声网定义的错误处理策略,可选值:error_abort
streamTypesString声网定义的订阅媒体流类型,当前可选值:0
serviceParamObject扩展服务的具体参数设置,详见 ServiceParam 数据结构

ServiceParam 数据结构

参数名称类型是否必填说明
secretIdString图普应用 SID
callbackString识别结果回调接口地址,用于接收 POST 回调
callbackAddrString声网新增的必填参数,实际传 - 即可,避免参数校验不通过
timestampNumber当前服务器的 Unix 时间戳
nonceNumber随机数
signatureString

RSA-SHA256 算法签名。签名步骤:

  1. 将参与签名的参数(secretIdtimestampnonce)用英文半角逗号 , 拼接,得到 SignString
  2. 使用您的私钥以 RSA-SHA256 算法对 SignString 签名,然后进行 Base64 编码,得到 signature 字符串。
  • 点击 数字证书 下载私钥。私钥有 rsapkcs8 两种格式,通常 Golang,Python 使用 rsa 格式私钥,Java 使用 pkcs8 格式私钥
  • 点击 签名及验证示例 查看签名示例
callbackRuleString回调规则,主要影响审核场景的识别任务,如语音转译审核、低俗语音识别,默认为 violation

violation:仅回调违规片段的识别结果;
all:回调所有片段的识别结果
roomIdString房间 ID(指定时可在控制台根据此字段搜索识别结果)
userIdString用户 ID(指定时可在控制台根据此字段搜索识别结果)
forumIdString板块 ID(指定时可在控制台根据此字段搜索识别结果)

2.2 请求示例

{
"cname": "<cname>",
"uid": "<uid>",
"clientRequest": {
"recordingConfig": {
"channelType": 0,
"maxIdleTime": 30,
"streamTypes": 0
},
"extensionServiceConfig": {
"errorHandlePolicy": "error_abort",
"extensionServices": [
{
"serviceName": "tupu_voice_scan",
"errorHandlePolicy": "error_abort",
"streamTypes": 0,
"serviceParam": {
"secretId": "<secretId>",
"callback": "<callback>",
"callbackAddr": "-",
"callbackRule": "all",
"roomId": "<roomId>",
"userId": "<userId>",
"forumId": "<forumId>",
"timestamp": 1685000000,
"nonce": 1685000000,
"signature": "<signature>"
}
}
]
}
}
}

3. 同步响应

略。参考声网 开始云端录制接口

4. 回调请求

4.1 请求地址

callback 参数指定的地址。

4.2 请求方法

POST

4.3 请求头

Content-Type: application/json

4.4 超时时间及异常处理

回调超时时间 5 秒,在 HTTP 响应状态码非 200 时进行重试,最多重试 3 次。

建议客户在处理回调时进行异步处理,响应回调时可以返回字符串或 JSON,示例如下:

// JSON
{
"message": "ok"
}

// 字符串
success

4.5 请求参数说明

参数名称类型说明
signatureString

同步响应或回调请求签名,由图普使用私钥签名,在需要时,您可以通过 图普公钥 进行验签以确保此响应内容来自图普(与您调用接口时使用的公私钥不同)。验签步骤:

  1. json 字段内容为 SignString
  2. signature 字段内容进行 Base64 解码,得到 RawSignature
  3. 使用图普公钥以 SHA256 算法验证 RawSignatureSignString
jsonString

同步响应或回调请求经过 JSON 转义后的字符串,需进一步解析得到业务数据。

  • 字段内容示例:{\"code\":0,\"message\":\"success\"}
  • 字段详见下述 json 参数说明;
  • 为方便展示,同步响应及回调请求的示例中,均为解析后的 JSON

json 参数说明

参数名称类型是否必有说明
codeNumber状态码,详见 业务状态码
requestIdString任务唯一 ID
roomIdString提交的房间 ID
userIdString提交的用户 ID
forumIdString提交的板块 ID
<任务 ID>Object识别任务结果,不同任务数据结构不同,详见 具体任务识别结果回调

4.6 请求示例

{
"code": 0,
"message": "success",
"requestId": "<requestId>",
"roomId": "<roomId>",
"userId": "<userId>",
"forumId": "<forumId>",
"5c8213b9bc807806aab0a574": {
"segments": [
{
"label": 0,
"review": false,
"speechUrl": "https://static.tuputech.com/api/image/original/cloud-api/storage-0831/2023-05-31/15-7/ec3249c2c68c475da82acfa0e01da544/1685518035.6439307480301700542.wav",
"startTime": 1685000000,
"endTime": 1685000010
}
]
},
"5ca1bd6b3872ecc9afb99132": {
"segments": [
{
"content": "今天是二零一零年一月十九号星期二欢迎收看东方新闻我是小蕾我是袁名我们在上海的直播向各位问好",
"speechUrl": "https://static.tuputech.com/api/image/original/cloud-api/storage-0831/2023-05-31/15-7/ec3249c2c68c475da82acfa0e01da544/1685518035.6439307480301700542.wav",
"startTime": 1685000000,
"endTime": 1685000010
}
],
"text": "今天是二零一零年一月十九号星期二欢迎收看东方新闻我是小蕾我是袁名我们在上海的直播向各位问好"
},
"5caee6b2a76925c55a09a6d2": {
"segments": [
{
"label": "Politics",
"rate": 0.9607035630154159,
"review": false,
"action": "block",
"content": "昨天下午举行传达学习,贯彻胡锦涛总书记,在上海考察时的重要讲话精神,中共中央政治局委员上海市委书记俞正声强调",
"hasVoice": true,
"speechUrl": "https://static.tuputech.com/api/image/original/cloud-api/storage-0831/2023-05-31/15-7/ec3249c2c68c475da82acfa0e01da544/1685518035.7890524239124616494.wav",
"startTime": 1685000000,
"endTime": 1685000010,
"details": [
{
"keyword": "胡锦涛",
"hint": "胡锦涛",
"mainLabel": "Politics",
"subLabel": "Political_Negative_events"
}
]
}
],
"label": "Politics",
"review": false,
"rate": 0.9608212453978402,
"action": "block",
"text": "今天是二零一零年一月十九号星期二欢迎收看东方新闻我是小蕾我是袁名我们在上海的直播向各位问好。昨天下午举行传达学习,贯彻胡锦涛总书记,在上海考察时的重要讲话精神,中共中央政治局委员上海市委书记俞正声强调"
},
"5f59e4b71b29fa890e5472fb": {
"segments": [
{
"label": 1,
"review": false,
"speechUrl": "https://static.tuputech.com/api/image/original/cloud-api/storage-0831/2023-05-31/15-7/ec3249c2c68c475da82acfa0e01da544/1685518035.6439307480301700542.wav",
"startTime": 1685000000,
"endTime": 1685000010,
"details": [
{
"label": 1,
"rate": 0.9999990463256836,
"startTime": 2.8,
"endTime": 10
}
]
}
]
},
"nonce": 1685000000,
"timestamp": 1685000000
}

4.7 具体任务识别结果回调

5. 语音流结束状态回调

说明

v3.1 接口始终在语音流结束时回调;v3 接口仅在 callbackRules 设置了状态结束回调时才会回调。

使用建议:

  • 收到语音流结束状态回调时, 说明任务已结束;
  • code 的值不为 0,说明流异常结束,可根据 code 的值查询对应的异常结束类型。

5.1 请求参数说明

参数名称类型是否必有说明
signatureString

同步响应或回调请求签名,由图普使用私钥签名,在需要时,您可以通过 图普公钥 进行验签以确保此响应内容来自图普(与您调用接口时使用的公私钥不同)。验签步骤:

  1. json 字段内容为 SignString
  2. signature 字段内容进行 Base64 解码,得到 RawSignature
  3. 使用图普公钥以 SHA256 算法验证 RawSignatureSignString
jsonString

同步响应或回调请求经过 JSON 转义后的字符串,需进一步解析得到业务数据。

  • 字段内容示例:{\"code\":0,\"message\":\"success\"}
  • 字段详见下述 json 参数说明;
  • 为方便展示,同步响应及回调请求的示例中,均为解析后的 JSON

json 参数说明

参数名称类型是否必有说明
codeNumber状态码,0:正常结束(由客户主动关闭或流正常结束),其他状态码请参考 语音流结束状态码
requestIdString任务 ID
statusString语音流状态,end:语音流结束
nonceNumber随机数
timestampNumber当前服务器的 Unix 时间戳

5.2 语音流结束状态回调示例

{
"code": 0,
"requestId": "<requestId>",
"status": "end",
"nonce": 1685000000,
"timestamp": 1685000000
}

6. 常见问题

6.1 开启语音流扩展服务后,未接收到识别结果回调

首先将回调规则设置为全部回调,观察是否能够收到识别结果回调。若仍无回调,请记录开始录制时声网返回 的 SessionID(录制 ID),提供给图普客户经理进行排查。