异步任务提交接口
更新时间:
请求规范
- 请求 URL:
从“控制台-服务配置”中获取
- 接口描述:
提交音频信息接口,信息提交后,会对音频进行检测,检测结果需自行调用音频结果获取接口获取。
- 支持格式:
音频文件格式支持:wav、mp3、aac、amr、3gp、m4a、wma、ogg、ape 等市场主流格式。
- 大小限制:
音频文件大小不超过550M ,时长小于5小时
- HTTP 请求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. (http://www.w3.org/TR/xmlschema-2/#dateTime)。
Authorization
签名值
-
请求方法:POST
-
请求体JSON对象:
参数
必需
类型
描述
type
必需
Number
1:音频URL 2: 音频文件BASE64值
注:推荐使用BASE64方式调用,音频URL在网络不佳时可能会造成音频下载缓慢或下载失败等问题
lang
必需
String
语言支持
audio
必需
String
音频内容,如type=1,则该值为音频URL,如type=2,则该值为音频BASE64值。type为2时,音频必须小于10m
audioName
可选
String
音频文件名字,当type=2,音频为BASE64值时,此参数为必需,且能表示音频格式
strategyId
Optional
String
策略编号,通过控制台配置。缺省时使用项目默认策略:DEFAULT
returnAllSeg
可选
Srting
0-只返回风险片段的结果,1-返回所有片段的结果
userId
可选
String
唯一的终端用户ID。 用户ID应当不超过32个字符。
userIP
可选
String
用户IP地址
did
可选
String
用户设备ID
dtype
可选
String
用户设备类型:1:iPhone 2:android 3: ipad 4:wphone 5: pc 6:web 7:wap
callbackRegion
可选
String
回调区域:默认cn,可选cn,us,ap。不给或不在取值范围内默认使用cn区域发起回调
callbackUrl
可选
String
回调url:http协议
callbackSecretKey
可选
String
回调密钥,可自行定义,需要在回调验签方式使用密钥一致,否则无法验证回调数据是否被篡改
country
可选
String
国家代码 ISO 3166-1 alpha-2
extra
可选
json
扩展字段,可以传多个key和value,透传。比如传游戏服务器和游戏版本两个参数,传入方式:“extra” : {“server”: “123”,“version”:“456”}
businessParams
可选
String
业务类型:噪音:NOISE
-
请求体示例:
JSON Response
{
"type":1,
"lang":"zh-CN",
"audio":"http://xxx.xxx.com/xxxx",
"userId": "testUser"
}
-
请求签名:
当用户请求Audio Submit API时,可以使用appId和secretKey(从“控制台-服务 配置“中获取)对请求做签名,当API收到带签名信息的请求之后,将使用相同的算法验证签名,如果发现签名不一致,API将会返回401给用户。
如果API验证签名一致,且appId对应的用户有权限操作请求的资源,则请求成功,否则API返回401。
- 通过 HTTP 请求 Header 发送签名
方法: 在请求中加入名为 Authorization 的 Header,值为签名值。如下:
Authorization: *****
- 签名计算方法
- 构造规范化的请求字符串(Canonicalized Query String)::
将请求体JSON字符串以UTF-8字符编码做sha256编码后转换为16进制字符串(注意不是Base64)
CanonicalizedQueryString = hex(sha256(jsonBody))
- 构造被签名字符串 StringToSign ("\n" 代表ASCII里的换行符)
StringToSign = HTTPMethod + "\n" +
HostHeaderInLowercase + "\n" +
HTTPRequestURI + "\n" +
CanonicalizedQueryString <从上一步得到> + "\n" +
"X-AppId:" + SAME_APPID_IN_HEADER + "\n" +
"X-TimeStamp:" + SAME_TIMESTAMP_IN_HEADER
HTTPRequestURI是请求URI的绝对路径,不包含请求串。如果HTTPRequestURI为空,也要保留一个正斜杠 ( / )
使用 HMAC-SHA256 协议创建基于哈希的消息身份验证代码 (HMAC),然后计算签名。
-
StringToSign作为签名字符串,secretKey作为秘钥,SHA256作为哈希算法
有关 HMAC 的更多信息,请参阅 https://tools.ietf.org/html/rfc2104。
-
将上一步的结果转换为BASE64串
-
将BASE64串放入HTTP请求Header的Authorization
- 签名示例
下面是appId & secretKey & audio的示例
appId=****
secrectKey=****
audio_url="http://xxx.xxx.com/xxxx"
下面是示例请求体
{
"type": 1,
"audio":"http://xxx.xxx.com/xxxx",
"userId": "12345678"
}
生成CanonicalizedQueryString
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
生成StringToSign
POST
asafe.ilivedata.com
/api/v1/audio/check/submit
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
X-AppId:***
X-TimeStamp:2020-07-31T07:59:03Z
HMAC计算得到的签名
*****
HTTP响应
Content-Type: application/json;charset=UTF-8
结果为JSON格式,请参考以下示例。
- HTTP响应
返回json字段说明:
字段名
类型
描述
errorCode
Number
错误码:0表示成功
errorMessage
String
错误消息
result
json对象
结果信息
result:
字段名
类型
描述
taskId
String
任务id,用于调用音频结果获取接口
-
响应示例1:
JSON response
{
"errorCode": 0,
"result":
{
"taskId":"f67fee0890de4c118d4f672b7c8ee304"
}
}
错误码
Http状态码
错误码
错误消息
200
0
此字段省略
405
1004
Method Not Allowed
411
1007
Not Content Length
400
1002
API Not Found
400
1003
Bad Request
401
1102
Unauthorized Client
401
1106
Missing Access Token
401
1107
Invalid Token
401
1108
Expired Token
401
1110
Invalid Client
400
2000
Missing Parameter
400
2001
Invalid Parameter
请求规范
- 请求 URL:
从“控制台-服务配置”中获取
- 接口描述:
提交音频信息接口,信息提交后,会对音频进行检测,检测结果需自行调用音频结果获取接口获取。
- 支持格式:
音频文件格式支持:wav、mp3、aac、amr、3gp、m4a、wma、ogg、ape 等市场主流格式。
- 大小限制:
音频文件大小不超过550M ,时长小于5小时
- HTTP 请求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. (http://www.w3.org/TR/xmlschema-2/#dateTime)。 | |
Authorization | 签名值 |
-
请求方法:POST
-
请求体JSON对象:
参数 | 必需 | 类型 | 描述 |
---|---|---|---|
type | 必需 | Number | 1:音频URL 2: 音频文件BASE64值 注:推荐使用BASE64方式调用,音频URL在网络不佳时可能会造成音频下载缓慢或下载失败等问题 |
lang | 必需 | String | 语言支持 |
audio | 必需 | String | 音频内容,如type=1,则该值为音频URL,如type=2,则该值为音频BASE64值。type为2时,音频必须小于10m |
audioName | 可选 | String | 音频文件名字,当type=2,音频为BASE64值时,此参数为必需,且能表示音频格式 |
strategyId | Optional | String | 策略编号,通过控制台配置。缺省时使用项目默认策略:DEFAULT |
returnAllSeg | 可选 | Srting | 0-只返回风险片段的结果,1-返回所有片段的结果 |
userId | 可选 | String | 唯一的终端用户ID。 用户ID应当不超过32个字符。 |
userIP | 可选 | String | 用户IP地址 |
did | 可选 | String | 用户设备ID |
dtype | 可选 | String | 用户设备类型:1:iPhone 2:android 3: ipad 4:wphone 5: pc 6:web 7:wap |
callbackRegion | 可选 | String | 回调区域:默认cn,可选cn,us,ap。不给或不在取值范围内默认使用cn区域发起回调 |
callbackUrl | 可选 | String | 回调url:http协议 |
callbackSecretKey | 可选 | String | 回调密钥,可自行定义,需要在回调验签方式使用密钥一致,否则无法验证回调数据是否被篡改 |
country | 可选 | String | 国家代码 ISO 3166-1 alpha-2 |
extra | 可选 | json | 扩展字段,可以传多个key和value,透传。比如传游戏服务器和游戏版本两个参数,传入方式:“extra” : {“server”: “123”,“version”:“456”} |
businessParams | 可选 | String | 业务类型:噪音:NOISE |
-
请求体示例:
JSON Response { "type":1, "lang":"zh-CN", "audio":"http://xxx.xxx.com/xxxx", "userId": "testUser" }
-
请求签名:
当用户请求Audio Submit API时,可以使用appId和secretKey(从“控制台-服务 配置“中获取)对请求做签名,当API收到带签名信息的请求之后,将使用相同的算法验证签名,如果发现签名不一致,API将会返回401给用户。
如果API验证签名一致,且appId对应的用户有权限操作请求的资源,则请求成功,否则API返回401。
- 通过 HTTP 请求 Header 发送签名
方法: 在请求中加入名为 Authorization 的 Header,值为签名值。如下:
Authorization: *****
- 签名计算方法
- 构造规范化的请求字符串(Canonicalized Query String)::
将请求体JSON字符串以UTF-8字符编码做sha256编码后转换为16进制字符串(注意不是Base64)
CanonicalizedQueryString = hex(sha256(jsonBody))
- 构造被签名字符串 StringToSign ("\n" 代表ASCII里的换行符)
StringToSign = HTTPMethod + "\n" +
HostHeaderInLowercase + "\n" +
HTTPRequestURI + "\n" +
CanonicalizedQueryString <从上一步得到> + "\n" +
"X-AppId:" + SAME_APPID_IN_HEADER + "\n" +
"X-TimeStamp:" + SAME_TIMESTAMP_IN_HEADER
HTTPRequestURI是请求URI的绝对路径,不包含请求串。如果HTTPRequestURI为空,也要保留一个正斜杠 ( / )
使用 HMAC-SHA256 协议创建基于哈希的消息身份验证代码 (HMAC),然后计算签名。
-
StringToSign作为签名字符串,secretKey作为秘钥,SHA256作为哈希算法
有关 HMAC 的更多信息,请参阅 https://tools.ietf.org/html/rfc2104。
-
将上一步的结果转换为BASE64串
-
将BASE64串放入HTTP请求Header的Authorization
- 签名示例
下面是appId & secretKey & audio的示例
appId=****
secrectKey=****
audio_url="http://xxx.xxx.com/xxxx"
下面是示例请求体
{
"type": 1,
"audio":"http://xxx.xxx.com/xxxx",
"userId": "12345678"
}
生成CanonicalizedQueryString
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
生成StringToSign
POST
asafe.ilivedata.com
/api/v1/audio/check/submit
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
X-AppId:***
X-TimeStamp:2020-07-31T07:59:03Z
HMAC计算得到的签名
*****
HTTP响应
Content-Type: application/json;charset=UTF-8
结果为JSON格式,请参考以下示例。
- HTTP响应
返回json字段说明:
字段名 | 类型 | 描述 |
---|---|---|
errorCode | Number | 错误码:0表示成功 |
errorMessage | String | 错误消息 |
result | json对象 | 结果信息 |
result:
字段名 | 类型 | 描述 |
---|---|---|
taskId | String | 任务id,用于调用音频结果获取接口 |
-
响应示例1:
JSON response
{ "errorCode": 0, "result": { "taskId":"f67fee0890de4c118d4f672b7c8ee304" } }
错误码
Http状态码 | 错误码 | 错误消息 |
---|---|---|
200 | 0 | 此字段省略 |
405 | 1004 | Method Not Allowed |
411 | 1007 | Not Content Length |
400 | 1002 | API Not Found |
400 | 1003 | Bad Request |
401 | 1102 | Unauthorized Client |
401 | 1106 | Missing Access Token |
401 | 1107 | Invalid Token |
401 | 1108 | Expired Token |
401 | 1110 | Invalid Client |
400 | 2000 | Missing Parameter |
400 | 2001 | Invalid Parameter |