# 一、接口说明

将长段音频文件(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 获取结果

# 调用流程

avatar

# 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、初始化转写任务

对于大文件的上传,建议将大文件分段,采用多次追加上传的方式,降低网络中断的风险。

# 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

# 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

# 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

# 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热词

# 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

# 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:单词内容。

# 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,
            "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,
            "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

# 七、错误码

错误码 说明 解决办法
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