# 一、接口说明

将长段音频文件（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热词
track_mode String 否 声道分轨模式，可选值：1，2
1: 表示不分轨，如果为多声道音频，会mix在一起识别
2: 表示分轨，此功能适用于双声道音频发音人分离场景，要求双声道音频每个声道是独立发音人，开启此功能时参数speaker_seperate失效
默认为1
计费规则:
该值为1时，按音频实际时长计费
该值为2时，按音频实际时长*2计费
speaker_seperate String 否 speaker_seperate
开启：“true“
关闭：“false”
注：此功能适用于根据声纹分离的场景，多声道音频会将多个声道的声音mix到一起再识别
默认false
speaker_num String 否 发音人个数，可选值：0-10，0表示盲分
默认0

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

# 七、错误码

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

← WebSocket文档 →