性别年龄识别 API 文档
接口说明
性别年龄识别,即机器对说话者的年龄大小以及性别属性进行分析,可以通过收到的音频数据判定发音人的性别(男,女)及年龄范围(小孩,中年,老人),对语音内容和语种不做限制。
部分开发语言demo如下,其他开发语言请参照文档进行开发,也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。
性别年龄识别demo go语言
性别年龄识别demo java语言
性别年龄识别demo python3语言
性别年龄识别demo nodejs语言集成性别年龄识别API时,需按照以下要求。
内容 | 说明 |
---|---|
请求协议 | ws[s] (为提高安全性,强烈推荐wss) |
请求地址 | ws[s]: //ws-api.xfyun.cn/v2/igr 注:服务器IP不固定,为保证您的接口稳定,请勿通过指定IP的方式调用接口,使用域名方式调用 |
请求行 | GET /v2/igr HTTP/1.1 |
接口鉴权 | 签名机制,详情请参照下方鉴权说明 |
字符编码 | UTF-8 |
响应格式 | 统一采用JSON格式 |
开发语言 | 任意,只要可以向讯飞云服务发起Websocket请求的均可 |
操作系统 | 任意 |
音频属性 | 采样率16k或8K、位长16bit、单声道 |
音频格式 | PCM、WAV、SPEEX、AMR,样例音频可点击 这里 下载 |
音频大小 | 最长10s,大小不得超过320K。建议持续发音5s左右,太短会影响识别效果 |
音频内容 | 任意 |
语言种类 | 任意 |
白名单
默认关闭IP白名单,即该服务不限制调用IP。
在调用该业务接口时
- 若关闭IP白名单,接口认为IP不限,不会校验IP。
- 若打开IP白名单,则服务端会检查调用方IP是否在讯飞开放平台配置的IP白名单中,对于没有配置到白名单中的IP发来的请求,服务端会拒绝服务。
IP白名单规则
- 在 控制台-相应服务的IP白名单处编辑,保存后五分钟左右生效。
- 不同Appid的不同服务都需要分别设置IP白名单。
- IP白名单需设置为外网IP,请勿设置局域网IP;
- 如果握手阶段返回{"message":"Your IP address is not allowed"},则表示由于IP白名单配置有误或还未生效,服务端拒绝服务。
鉴权说明
在握手阶段,请求方需要对请求进行签名,服务端通过签名来校验请求的合法性。
鉴权方法
通过在请求地址后面加上鉴权相关参数的方式。示例url:
wss://ws-api.xfyun.cn/v2/igr?authorization=aG1hYyB1c2VybmFtZT0iMTAwSU1FIiwgYWxnb3JpdGhtPSJobWFjLXNoYTI1NiIsIGhlYWRlcnM9Imhvc3QgZGF0ZSByZXF1ZXN0LWxpbmUiLCBzaWduYXR1cmU9IlVSbnk4M3o1elJsNWF1ODl1YXhUL1dGdUtWejZVNkdkWDdDV25SMGdueWc9Ig%3D%3D&date=Tue%2C+18+Dec+2018+09%3A08%3A49+UTC&host=10.1.87.70%3A8000
鉴权参数:
参数 | 类型 | 必须 | 说明 | 示例 |
---|---|---|---|---|
host | string | 是 | 请求主机 | ws-api.xfyun.cn |
date | string | 是 | 当前时间戳,RFC1123格式(Mon, 02 Jan 2006 15:04:05 GMT) | Fri, 18 Jan 2019 07:21:29 UTC |
authorization | string | 是 | 使用base64编码的签名相关信息(签名基于hmac-sha256计算) | 参考下方authorization参数生成规则 |
- date参数生成规则:
date必须是UTC+0或GMT时区,RFC1123格式(Mon, 02 Jan 2006 15:04:05 GMT)。
服务端会对Date进行时钟偏移检查,最大允许300秒的偏差,超出偏差的请求都将被拒绝。
- authorization参数生成规则:
1)获取接口密钥APIKey 和 APISecret。
在讯飞开放平台控制台,创建WebAPI平台应用并添加性别年龄识别服务后即可查看,均为32位字符串。
2)参数authorization base64编码前(authorization_origin)的格式如下。
api_key="$api_key",algorithm="hmac-sha256",headers="host date request-line",signature="$signature"
其中 api_key 是在控制台获取的APIKey,algorithm 是加密算法(仅支持hmac-sha256),headers 是参与签名的参数。
signature 是使用加密算法对参与签名的参数签名后并使用base64编码的字符串,详见下方。
3)signature的原始字段(signature_origin)规则如下。
signature原始字段由 host,date,request-line三个参数按照格式拼接成,
拼接的格式为(\n为换行符,’:’后面有一个空格):
host: $host\ndate: $date\n$request-line
例如,请求的url为 wss://ws-api.xfyun.cn/v2/igr
那么 signature原始字段(signature_origin)则为:
host: ws-api.xfyun.cn
date: Fri, 18 Jan 2019 07:21:29 UTC
GET /v2/igr HTTP/1.1
4)使用hmac-sha256算法结合apiSecret对signature_origin签名,获得签名后的摘要signature_sha。
signature_sha=hmac-sha256(signature_origin,$apiSecret)
其中 apiSecret 是在控制台获取的APISecret
5)使用base64编码对signature_sha进行编码获得最终的signature。
signature=base64(signature_sha)
6)authorization_origin示例如下。
假设 api_key=23b18a1e80cf334f81b0ade291629a536f,参照上述2-4的方法生成的signature=clHXo7gfpxwjhC5vcRt2haKNosUfG8I7b8PMyT9pJEs=。
那么生成的base64编码前authorization_origin参数为:
api_key="23b18a1e80cf334f81b0ade291629a536f", algorithm="hmac-sha256", headers="host date request-line", signature="clHXo7gfpxwjhC5vcRt2haKNosUfG8I7b8PMyT9pJEs="
7)最后再对authorization_origin进行base64编码获得最终的authorization参数。
authorization = base64(authorization_origin)
鉴权url示例(golang)
//@hosturl : like wss://ws-api.xfyun.cn/v2/iat
//@apikey : apiKey
//@apiSecret : apiSecret
func assembleAuthUrl(hosturl string, apiKey, apiSecret string) string {
ul, err := url.Parse(hosturl)
if err != nil {
fmt.Println(err)
}
//签名时间
date := time.Now().UTC().Format(time.RFC1123)
//参与签名的字段 host ,date, request-line
signString := []string{"host: " + ul.Host, "date: " + date, "GET " + ul.Path + " HTTP/1.1"}
//拼接签名字符串
sgin := strings.Join(signString, "\n")
//签名结果
sha := HmacWithShaTobase64("hmac-sha256", sgin, apiSecret)
//构建请求参数 此时不需要urlencoding
authUrl := fmt.Sprintf("api_key=\"%s\", algorithm=\"%s\", headers=\"%s\", signature=\"%s\"", apiKey,
"hmac-sha256", "host date request-line", sha)
//将请求参数使用base64编码
authorization:= base64.StdEncoding.EncodeToString([]byte(authUrl))
v := url.Values{}
v.Add("host", ul.Host)
v.Add("date", date)
v.Add("authorization", authorization)
//将编码后的字符串url encode后添加到url后面
callurl := hosturl + "?" + v.Encode()
return callurl
}
鉴权结果
如果握手成功,会返回HTTP 101状态码,表示协议升级成功;如果握手失败,则根据不同错误类型返回不同HTTP Code状态码,同时携带错误描述信息,详细错误说明如下:
HTTP Code | 说明 | 错误描述信息 | 解决方法 |
---|---|---|---|
401 | 缺少authorization参数 | {“message”:”Unauthorized”} | 检查是否有authorization参数,详情见authorization参数详细生成规则 |
401 | 签名参数解析失败 | {“message”:”HMAC signature cannot be verified”} | 检查签名的各个参数是否有缺失是否正确,特别确认下复制的api_key是否正确 |
401 | 签名校验失败 | {“message”:”HMAC signature does not match”} | 签名验证失败,可能原因有很多。 1. 检查api_key,api_secret 是否正确。 2.检查计算签名的参数host,date,request-line是否按照协议要求拼接。 3. 检查signature签名的base64长度是否正常(正常44个字节)。 |
403 | 时钟偏移校验失败 | {“message”:”HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication”} | 检查服务器时间是否标准,相差5分钟以上会报此错误 |
403 | IP白名单校验失败 | {"message":"Your IP address is not allowed"} | 可在控制台关闭IP白名单,或者检查IP白名单设置的IP地址是否为本机外网IP地址 |
握手失败返回示例:
HTTP/1.1 401 Forbidden
Date: Thu, 06 Dec 2018 07:55:16 GMT
Content-Length: 116
Content-Type: text/plain; charset=utf-8
{
"message": "HMAC signature does not match"
}
请求参数
在调用业务接口时,都需要配置以下参数,请求数据均为json字符串。
请求参数示例:
{
"common":{
// 公共请求参数
"app_id":"123456"
},
"business":{
"aue": "raw",
"rate": "16000"
},
"data":{
"status":0,
"audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."
}
}
数据上传结束标识示例:
{
"data":{
"status":2
}
}
请求参数说明:
参数名 | 类型 | 必传 | 描述 |
---|---|---|---|
common | object | 是 | 公共参数,仅在握手成功后首帧请求时上传,详见下方 |
business | object | 是 | 业务参数,仅在握手成功后首帧请求时上传,详见下方 |
data | object | 是 | 业务数据流参数,在握手成功后的所有请求中都需要上传,详见下方 |
公共参数说明(common)
参数名 | 类型 | 必传 | 描述 |
---|---|---|---|
app_id | string | 是 | 在平台申请的APPID信息 |
注: 以上参数只需要在握手成功后的第一帧请求时带上。
业务参数说明(business)
参数名 | 类型 | 必传 | 描述 |
---|---|---|---|
ent | string | 是 | 引擎类型,目前仅支持igr |
aue | string | 是 | 音频格式 raw:原生音频数据pcm格式 speex:speex格式(rate需设置为8000) speex-wb:宽频speex格式(rate需设置为16000) amr:amr格式(rate需设置为8000) amr-wb:宽频amr格式(rate需设置为16000) |
rate | int | 是 | 音频采样率 16000/8000 |
注: SPEEX格式仅支持讯飞定制speex编码,压缩等级为7,编解码工具请点击 这里 下载。
业务参数说明(data)
参数名 | 类型 | 必传 | 描述 |
---|---|---|---|
status | int | 是 | 音频的状态 0 :第一帧音频 1 :中间的音频 2 :最后一帧音频,最后一帧必须要发送 |
audio | string | 是 | 音频的数据,需进行base64编码 |
返回结果
如出现错误码,可到 这里 查询。
返回参数示例:
{
"code": 0,
"message": "success",
"data": {
"result": {
"age": {
"age_type": "1",
"child": "0.4887",
"middle": "0.3180",
"old": "0.1933"
},
"gender": {
"female": "0.5933",
"gender_type": "0",
"male": "0.4067"
}
},
"status": 2
}
}
返回参数说明:
参数名 | 类型 | 描述 |
---|---|---|
sid | string | 本次会话的id,只在握手成功后第一帧请求时返回 |
code | int | 返回码,0表示成功,其它表示异常,详情请参考错误码 |
message | string | 描述信息 |
data | json | 性别年龄识别返回信息,详见下方 |
data字段具体信息
参数名 | 类型 | 描述 |
---|---|---|
status | int | 返回结果状态 1:后续还会有结果 2:结果已经全部返回,客户端可以关闭连接 |
result | object | 返回数据的具体对象 |
result.age | object | 识别的年龄数据对象 |
result.age.age_type | string | 表示识别的年龄 0:middle(12~40岁) 1:child(0~12岁) 2:old(40岁以上) |
result.age.child | string | 表示识别为儿童的概率值,儿童、中年、老年概率值最大的为最终结果 |
result.age.middle | string | 表示识别为中年的概率值,儿童、中年、老年概率值最大的为最终结果 |
result.age.old | string | 表示识别为老年的概率值,儿童、中年、老年概率值最大的为最终结果 |
result.gender | object | 识别的性别数据对象 |
result.gender.gender_type | string | 表示识别的性别 0:女性 1:男性 |
result.gender.female | string | 表示识别为女声的概率值,女声、男声概率值较大的为最终结果 |
result.gender.male | string | 表示识别为男声的概率值,女声、男声概率值较大的为最终结果 |
音频样例
注: 音频文件格式转换工具请参考这里 ffmpeg
常见问题
性别年龄识别的主要功能是什么?
答:机器对说话者的年龄大小以及性别属性进行分析,可以通过收到的音频数据判定发音人的性别(男,女)及年龄(小孩,中年,老人)。
性别年龄识别支持什么应用平台?
答:目前性别年龄识别支持Web api应用平台。
性别年龄识别支持什么音频格式?
答:音频最长支持10s,大小不得超过320K。建议上传的音频中发音人连续发音时间持续5秒左右,音频太短会影响识别效果。
性别年龄识别返回的识别结果是什么?
答:返回的声音特征识别结果包括年龄段(小孩、中年、老人)和性别(男性、女性),并会给出对应概率值。
性别年龄识别如何免费试用吗?价格是多少?
答:登录讯飞开放平台---控制台---我的应用(没有应用先创建一个应用)---语音扩展---性别年龄识别(2万次/日免费服务),价格详情参考性别年龄识别服务首页