- ···
- 产品服务
- ···
- 解决方案
- ···
- 文档中心
- ···
# 一、接口说明
将长段音频文件(5小时以内或文件大小在2G以下)转换成文本数据,商业用户可在6小时之内获得识别文本。适用于会议转写、字幕生成、音频内容分析等场景。
# 二、接口Demo
Java示例demo (opens new window)
python3示例demo (opens new window)
js示例demo (opens new window)
# 三、接口要求
集成音频文件转写API时,需按照以下要求:
内容 | 说明 |
---|---|
请求协议 | http[s] (为提高安全性,强烈推荐https) |
请求方式 | POST/GET |
请求地址 | http[s]: //af-asr.hivoice.cn |
接口鉴权 | 签名机制,详情请参照下方接口鉴权 |
字符编码 | UTF-8 |
响应格式 | 统一采用JSON格式 |
开发语言 | 任意,只要可以向服务发起发起HTTP请求的均可 |
操作系统 | 任意 |
音频属性 | 采样率16k或8k,采样深度16bit、单声道 |
音频格式 | mp3、opus、wav、amr、m4a、ogg |
音频长度 | 5小时以内或文件大小在2G以下 |
语言种类 | 中文普通话、英语 |
# 四、ip白名单
默认关闭IP白名单,即该服务不限制调用IP。 在调用该业务接口时
- 若关闭IP白名单,接口认为IP不限,不会校验IP。
- 若打开IP白名单,则服务端会检查调用方IP是否在开放平台配置的IP白名单中,对于没有配置到白名单中的IP发来的请求,服务端会拒绝服务。
- 若打开IP白名单,同时没有设置任何IP,接口会认为此时没有设置白名单,所以打开IP白名单时,请务必设置IP,否则无法生效。
IP白名单规则
- 登录 云知声AI开放平台控制台 (opens new window)
- 选择应用的查看详情
- IP白名单处编辑,保存后五分钟左右生效。
- 不同appkey的不同服务都需要分别设置IP白名单。
- IP白名单需设置为外网IP,请勿设置局域网IP。
# 五、热词
音频文件转写支持应用级个性化热词和用户级别个性话热词,具体设置方法参考设置热词
# 六、接口调用流程
# 接口列表
接口名 | URI | 请求方式 | 说明 |
---|---|---|---|
init | /utservice/v2/trans/append_upload/init | POST | 初始化转写任务 |
upload | /utservice/v2/trans/append_upload/upload | POST | 追加上传音频 |
transcribe | /utservice/v2/trans/transcribe | POST | 开始转写 |
text | /utservice/v2/trans/text | GET | 获取结果 |
# 调用流程
# 1、接口鉴权
通用参数:通用参数是转写服务所有API的公有参数。
参数名称 | 参数类型 | 是否必填 | 描述 |
---|---|---|---|
timestamp | long | 是 | 请求的时间戳(使用 Unix 时间戳) |
signature | String | 是 | 请求签名 |
appkey | String | 是 | 识别使用的appKey |
# 签名流程
SHA1签名计算公式: sign = SHA1(请求字符串).toUpperCase
- 将请求参数的值按照参数名称的字典序进行排序,如请求参数为:userid=user001&audiotype=wav&domain=news&appkey=xxx&timstamp=1545016319978
- 按照字典序拼接的字符串为:xxxwavnews1545016319978user001
- 将开发者 appSecret 拼接到字符串的两端:如 secret 为:8934e7d15453e97507ef794cf7b0519d,则拼接后为:8934e7d15453e97507ef794cf7b0519dxxxwavnews1545016319978user0018934e7d15453e97507ef794cf7b0519d
签名的结果为:
sign=SHA1(8934e7d15453e97507ef794cf7b0519dxxxwavnews1545016319978user0018934e7d15453e97507ef794cf7b0519d).toUpperCase = 4C513CB879523CA9D717EEA7819DEB0C
SHA1签名算法Java示例
/**
* SHA1加密
*
* @param decrypt
* @return
*/
public static String encryptSHA1(String decrypt) {
try {
MessageDigest digest = MessageDigest.getInstance("SHA-1");
digest.update(decript.getBytes("UTF-8"));
byte messageDigest[] = digest.digest();
// Create Hex String
StringBuffer hexString = new StringBuffer();
// 字节数组转换为 十六进制 数
for (int i = 0; i < messageDigest.length; i++) {
String shaHex = Integer.toHexString(messageDigest[i] & 0xFF);
if (shaHex.length() < 2) {
hexString.append(0);
}
hexString.append(shaHex);
}
return hexString.toString();
} catch (Exception e) {
return "";
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 2、初始化转写任务
对于大文件的上传,建议将大文件分段,采用多次追加上传的方式,降低网络中断的风险。
# 2.1、参数说明
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
userid | String | 是 | 请求的用户 id。说明:可由数字、字母(区分大小写)、和下划线组成,支持最大长度不超过20个字节 |
# 2.2、 请求示例
POST http://af-asr.hivoice.cn/utservice/v2/trans/append_upload/init?userid=xxxx&appkey=xxx&timstamp=1545016319978&signature=xxx HTTP/1.1
1
# 2.3、请求返回示例
HTTP/1.1 200 OK
Content-Type: application/json;
{
"task_id": " 68753A444D6F12269C600050E4C00067",
"error_code": 0,
"message": "OK"
}
1
2
3
4
5
6
7
2
3
4
5
6
7
# 3、追加上传音频
此接口支持追加上传,使用相同task_id上传多次默认为追加上传。
# 3.1 参数说明
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
userid | String | 是 | 请求的用户 id |
task_id | String | 是 | 由语音文件上传的初始化接口的返回获得 |
audiotype | String | 是 | 请求的语音文件类型。支持的语音类型: mp3、opus、wav、amr、m4a、ogg |
md5 | String | 是 | 上传文件的MD5码值,用于文件完整性校验。 |
# 3.2、 请求示例
POST http://af-asr.hivoice.cn/utservice/v2/trans/append_upload/upload?userid=xxxx&md5=XXX&task_id=68753A444D6F12269C600050E4C00067&audio_type=wav&appkey=xxx&timstamp=1545016319978&signature=xxx HTTP/1.1
Content-Type: application/octet-stream;
Content-Length: N
content of audio[语音文件的二进制数据]
1
2
3
4
2
3
4
# 3.3、请求返回示例
HTTP/1.1 200 OK
Content-Type: application/json;
{
"task_id": " 68753A444D6F12269C600050E4C00067",
"error_code": 0,
"message": "OK"
}
1
2
3
4
5
6
7
2
3
4
5
6
7
# 4、开始转写
当所有音频上传完毕后,调用此接口开始转写
# 4.1 参数说明
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
userid | String | 是 | 请求的用户 id |
task_id | String | 是 | 由语音文件上传的初始化接口的返回获得 |
audiotype | String | 是 | 请求的语音文件类型。支持的语音类型: mp3、opus、wav、amr、m4a、ogg |
domain | String | 是 | 支持的识别领域: law 司法 finance 财经 technology 科技 medical 医疗 emotions 情感 news 时事新闻 other 其他 |
md5 | String | 是 | 上传文件的MD5码值,用于文件完整性校验。 |
word_info | String | 否 | 是否返回单词的时间边界信息: 返回:“true“ 不返回:“false” |
punction | String | 否 | 返回结果的标点类型 none:无标点 beauty:专业标点 |
lang | String | 否 | 语言类型 中文:“cn” 英文:“en” 默认中文 |
num_convert | String | 否 | 请求数字后处理,将大写数字转换成阿拉伯数字 开启:“true“ 关闭:“false” 默认关闭 |
sens_words_filter | String | 否 | 敏感词过滤功能,将敏感词替换成* 开启:“true“ 关闭:“false” 默认关闭 |
vocab_id | String | 否 | 热词ID(调用热词服务时返回),获取方法参考设置vocab热词 |
track_mode | String | 否 | 声道分轨模式,可选值:1,2 1: 表示不分轨,如果为多声道音频,会mix在一起识别 2: 表示分轨,此功能适用于双声道音频发音人分离场景,要求双声道音频每个声道是独立发音人,开启此功能时参数speaker_seperate失效 默认为1 计费规则: 该值为1时,按音频实际时长计费 该值为2时,按音频实际时长*2计费 |
speaker_seperate | String | 否 | speaker_seperate 开启:“true“ 关闭:“false” 注:此功能适用于根据声纹分离的场景,多声道音频会将多个声道的声音mix到一起再识别 默认false |
# 4.2、 请求示例
POST http://af-asr.hivoice.cn/utservice/v2/trans/transcribe?userid=user001&task_id=XXX&audio_type=wav&domain=news&md5=XXX&appkey=xxx&timstamp=1545016319978&signature=xxx HTTP/1.1
1
# 4.3、请求返回示例
HTTP/1.1 200 OK
Content-Type: application/json;
{
"task_id": " 68753A444D6F12269C600050E4C00067",
"error_code": 0,
"message": "OK"
}
1
2
3
4
5
6
7
2
3
4
5
6
7
# 5、获取转写结果
获取转写的文本结果,转写的文本结果最多保存 10 天
# 5.1 参数说明
参数名 | 类型 | 是否必填 | 描述 |
---|---|---|---|
task_id | String | 是 | 由语音文件上传初始化接口的返回获得 |
# 5.2、 请求示例
GET http://af-asr.hivoice.cn/utservice/v2/trans/text?task_id=xxxx&appkey=xxx&timstamp=1545016319978&signature=xxx HTTP/1.1
1
# 5.3 返回结果说明
参数名 | 类型 | 描述 | 是否可能为空 |
---|---|---|---|
error_code | String | 错误码返回字段说明 | 否 |
message | String | 错误信息 | 否 |
status | String | 由语音文件上传初始化接口的返回获得 done 为完成 running 为转写中 waiting为等待转写 | 是 |
use_hot_data | String | 本次转写是否使用了热词 | 是 |
duration | int | 语音时长,单位 ms | 是 |
start_time | long | 开始转写的时间,Unix 时间戳 | 是 |
cost_time | int | 转写耗时,单位 ms | 是 |
progress | int | 已经完成转写的语音时长,单位 ms | 是 |
results | Array | 分片转写结果集合,数据结构参考result | 是 |
说明
- 当error_code表示异常时,error_code和message之外的字段都可能为空
result结构体
参数名 | 类型 | 描述 | 是否可能为空 |
---|---|---|---|
index | int | 分片序号 | 否 |
start | int | 分片开始时间,单位ms | 否 |
end | int | 分片结束时间,单位ms | 否 |
text_length | int | 转写结果长度 | 否 |
text | String | 转写结果 | 是 |
word_info | Array | (开启word_info设置才会返回该字段): 单词时间边界信息。 b:开始时间;e:结束时间;w:单词内容。 | 是 |
speaker | int | 说话人编号 从1开始递增,未开启说话人分离时speaker均为0 | 否 |
# 5.4、请求返回示例
HTTP/1.1 200 OK
Content-Type: application/json;
{
"duration": 4920,
"start_time": 1592363319322,
"use_hot_data": "false",
"cost_time": 2490,
"progress": 4920,
"error_code": 0,
"message": "OK",
"results": [
{
"start": 60,
"index": 0,
"end": 2130,
"speaker": 0,
"word_info": [
{
"b": 0,
"e": 60,
"w": "<s>"
},
{
"b": 60,
"e": 450,
"w": "北京"
},
{
"b": 450,
"e": 870,
"w": "今天"
},
{
"b": 870,
"e": 1050,
"w": "天气"
},
{
"b": 1050,
"e": 2070,
"w": "不错"
},
{
"b": 2070,
"e": 2100,
"w": "</s>"
}
],
"text": "北京今天天气不错。",
"text_length": 9
},
{
"start": 3450,
"index": 1,
"end": 4920,
"speaker": 0,
"word_info": [
{
"b": 2100,
"e": 3660,
"w": "明天"
},
{
"b": 3660,
"e": 4110,
"w": "也"
},
{
"b": 4110,
"e": 4800,
"w": "还行"
},
{
"b": 4800,
"e": 4920,
"w": "</s>"
}
],
"text": "明天也还行。",
"text_length": 6
}
],
"status": "done"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
# 七、错误码
错误码 | 说明 | 解决办法 |
---|---|---|
0 | 正常 | |
1001 | 请求参数错误 | 客户端检查参数是否正确 |
1002 | appkey白名单校验失败 | 确认此appkey是否拥有白名单权限 |
1003 | ip白名单校验失败 | 检查是否开启白名单,同时检查客户端出口ip是否在ip白名单中 |
1004 | appkey访问频率过高 | 检查客户端是否有异常调用,控制一下调用频率 |
1011 | 文件上传失败 | 检查网络是否有过异常,失败后建议重试 |
1012 | 文件上传md5校验错误 | 检查上传文件是否有过异常,建议重试 |
1021 | 转写任务重复执行 | 检查此任务是否已经触发过转写 |
1022 | 获取语音文件错误 | 建议重试,或者提工单,工单详情请提供task_id |
1023 | 语音文件md5校验错误 | 建议重试,或者提工单,工单详情请提供task_id |
1024 | 语音文件格式转换失败 | 建议重试,或者提工单,工单详情请提供task_id |
1025 | 获取服务处理节点失败 | 建议重试,或者提工单,工单详情请提供task_id |
1026 | 语音识别过程中异常 | 建议重试,或者提工单,工单详情请提供task_id |
1027 | 转写错误 | 建议重试,或者提工单,工单详情请提供task_id |
1041 | 获取结果失败 | 建议重试,或者提工单,工单详情请提供task_id |
← WebAPI文档 WebSocket文档 →