语音转写 API 文档

接口说明

语音转写：（Long Form ASR）基于深度全序列卷积神经网络，将长段音频（5 小时以内）数据转换成文本数据，为信息处理和数据挖掘提供基础。

接口要求

集成语音转写 API 时，需按照以下要求。

请求地址：

注：服务器 IP 不固定，为保证您的接口稳定，请勿通过指定 IP 的方式调用接口，使用域名方式调用_

http[s]: //raasr.xfyun.cn/api/xxx

内容	说明
请求协议	http[s]（为提高安全性，强烈推荐 https）
请求方式	POST
接口鉴权	签名机制
字符编码	UTF-8
响应格式	统一采用 JSON 格式
开发语言	任意
音频属性	采样率 16k 或 8k、位长 8bits 或 16bits、单声道&多声道
音频格式	wav/flac/opus/m4a/mp3
音频大小	不超过 500M
音频时长	不超过 5 小时，建议 5 分钟以上
语言种类	中文普通话、英文
转写结果保存时长	30 天
获取结果次数	不得超过 100 次
SLA 保障时长	返回时长最大不超过 12 小时

接口调用流程

转写 API 包括以下接口：预处理、文件分片上传、合并文件、查询处理进度、获取结果。

预处理 /prepare:
文件分片上传 /upload:
合并文件 /merge:
查询处理进度 /getProgress:
获取结果 /getResult:

转写流程图

通用返回说明：

参数	类型	说明
ok	int	调用成功标志（0：成功，-1：失败）
err_no	int	错误码
failed	string	错误描述（null：未出错）
data	string	数据，具体含义见各接口返回说明（null：无返回值）
task_id	string	任务 id，此字段只在主动回调的结果中存在

1、预处理接口

概述

	首先调用预处理接口，上传待转写音频文件的基本信息（文件名、大小）和分片信息（建议分片大小设置为10M，若无需分片，slice_num=1）和相关的可配置参数。
	调用成功，返回任务ID（task_id，转写任务的唯一标识），是后续接口的必传参数。

URL

	POST https://aicp.teamshub.com/sitech/aiopen//file/voice2text

请求头

	Content-Type: application/x-www-form-urlencoded; charset=UTF-8

参数说明

参数	类型	必须	说明
app_id	string	是	应用 ID
signa	string	是	加密数字签名
ts	string	是	当前时间戳
file_len	string	是	文件大小（单位：字节）
file_name	string	是	文件名称（带后缀）
slice_num	int	是	文件分片数目（建议分片大小为 10M，若文件<10M，则 slice_num=1）
lfasr_type	string	否	转写类型，默认 0 0: (标准版，格式: wav,flac,opus,mp3,m4a) 2: (电话版，已取消)
has_participle	string	否	转写结果是否包含分词信息
max_alternatives	string	否	转写结果中最大的候选词个数
speaker_number	string	否	发音人个数，可选值：0-10，0 表示盲分注：发音人分离目前还是测试效果达不到商用标准，如测试无法满足您的需求，请慎用该功能。
has_seperate	string	否	转写结果中是否包含发音人分离信息
role_type	string	否	支持两种参数 1: 通用角色分离 2: 电话信道角色分离（适用于 speaker_number 为 2 的说话场景）
language	string	否	语种 cn:中英文&中文（默认） en:英文（英文不支持热词）
pd	string	否	垂直领域个性化参数: 法院: court 教育: edu 金融: finance 医疗: medical 科技: tech

返回值

成功

{
  "ok": 0,
  "err_no": 0,
  "failed": null,
  "data": "383e72a47557490aa05a344074117a9d"
}

失败

{
  "ok": -1,
  "err_no": 26601,
  "failed": "非法应用信息",
  "data": null
}

结果说明

调用成功，data 即为 taskId（任务 ID），是后续接口的必传参数。

2、文件分片上传接口

概述

	预处理成功，调用文件上传接口；
	按预处理设置的分片信息（slice_num）依次上传音频切片（文件以二进制方式读取上传），直到全部切片上传成功（如预处理时 slice_num=2，则需将音频切分成两部分，slice_id=aaaaaaaaaa和aaaaaaaaab，并按顺序调用该接口）；
	上一切片成功上传，才可进行下一切片的上传操作。调用过程中若出现异常，可重试若干次。

url

	POST  http[s]://raasr.xfyun.cn/api/upload

请求头

	Content-Type: multipart/form-data;

参数说明

参数	类型	必须	说明	示例
app_id	string	是	开放平台应用 ID	595f23df
signa	string	是	加密数字签名，详见下方	BFQEcN3SgZNC4eECvq0LFUPVHvI=
ts	string	是	时间戳	1512041814
task_id	string	是	任务 ID（预处理接口返回值）	4b705edda27a4140b31b462df0033cfa
slice_id	string	是	分片序号	aaaaaaaaaa，aaaaaaaaab
content	字节数组	是	分片文件内容

signa 生成

① 获取 baseString

	baseString由appid和当前时间戳ts拼接而成；
	假如appid = 595f23df，ts = 1512041814，则baseString = 595f23df1512041814

② 对 baseString 进行 MD5

	假如baseString为上一步生成的595f23df1512041814，MD5之后则为 0829d4012497c14a30e7e72aeebe565e

③ 以 secret key 为 key 对 MD5 之后的 baseString 进行 HmacSHA1 加密，然后再对加密后的字符串进行 base64 编码。

	假如secretkey = d9f4aa7ea6d94faca62cd88a28fd5234，
	MD5之后的baseString为上一步生成的0829d4012497c14a30e7e72aeebe565e，
	则HmacSHA1加密之后再进行base64编码得到的signa为： IrrzsJeOFk1NGfJHW6SkHUoN9CU=

备注：

secretkey：接口密钥，在应用中添加语音转写服务后，显示在服务管理页面，请调用方注意保管；
signa 的生成公式：HmacSHA1(MD5(appid + ts)，secretkey)，具体的生成方法详见；

返回值

成功

{
  "ok": 0,
  "err_no": 0,
  "failed": null,
  "data": null
}

失败

{
  "ok": -1,
  "err_no": 26602,
  "failed": "任务ID不存在",
  "data": null
}

slice_id 生成代码(python)示例

class SliceIdGenerator:
    """slice id生成器"""
    def __init__(self):
        self.__ch = 'aaaaaaaaa`'

    def getNextSliceId(self):
        ch = self.__ch
        j = len(ch) - 1
        while j >= 0:
            cj = ch[j]
            if cj != 'z':
                ch = ch[:j] + chr(ord(cj) + 1) + ch[j+1:]
                break
            else:
                ch = ch[:j] + 'a' + ch[j+1:]
                j = j -1
        self.__ch = ch
        return self.__ch

注：每个转写任务上传开始前创建一个 SliceIdGenerator，根据分片的顺序依次调用 getNextSliceId 生成对应的 slice_id

3、合并文件接口

概述

	全部文件切片上传成功后，调用该接口，通知服务端进行文件合并与转写操作。
	该接口不会返回转写结果，而是通知服务端将任务列入转写计划。转写的结果通过 getResult 接口获取。

url

	POST  http[s]://raasr.xfyun.cn/api/merge

请求头

	Content-Type: application/x-www-form-urlencoded; charset=UTF-8

参数说明

参数	类型	必须	说明	示例
app_id	string	是	开放平台应用 ID	595f23df
signa	string	是	加密数字签名	BFQEcN3SgZNC4eECvq0LFUPVHvI=
ts	string	是	时间戳	1512041814
task_id	string	是	任务 ID（预处理接口返回值）	4b705edda27a4140b31b462df0033cfa

返回值

成功

{
  "ok": 0,
  "err_no": 0,
  "failed": null,
  "data": null
}

失败

{
  "ok": -1,
  "err_no": 26602,
  "failed": "任务ID不存在",
  "data": null
}

4、查询处理进度接口

概述

	在调用方发出合并文件请求后，服务端已将任务列入计划。在获取结果前，调用方需轮询该接口查询任务当前状态。
	当且仅当任务状态=9（转写结果上传完成），才可调用获取结果接口获取转写结果。
	轮询策略由调用方决定，建议每隔10分钟轮询一次。状态码说明见附录。

url

	POST  http[s]://raasr.xfyun.cn/api/getProgress

请求头

	Content-Type: application/x-www-form-urlencoded; charset=UTF-8

参数说明

参数	类型	必须	说明	示例
app_id	string	是	开放平台应用 ID	595f23df
signa	string	是	加密数字签名	BFQEcN3SgZNC4eECvq0LFUPVHvI=
ts	string	是	时间戳	1512041814
task_id	string	是	任务 ID（预处理接口返回值）	4b705edda27a4140b31b462df0033cfa

返回值

成功

{
  "ok": 0,
  "err_no": 0,
  "failed": null,
  "data": "{\"desc\":\"任务创建成功\",\"status\":0}"
}

失败

{
  "ok": -1,
  "err_no": 26640,
  "failed": "文件上传失败",
  "data": null
}

处理流程

转写-查询处理进度流程图

5、获取结果接口

概述

	当任务处理进度状态=9（见查询处理进度接口），调用该接口获取转写结果。这是转写流程的最后一步。
	转写结果各字段的详细说明见转写结果说明文档。
	服务端也支持主动回调，转写完成之后主动发送转写结果到用户配置的回调地址，配置回调地址请联系技术支持。

url

	POST  http[s]://raasr.xfyun.cn/api/getResult

请求头

	Content-Type: application/x-www-form-urlencoded; charset=UTF-8

参数说明

参数	类型	必须	说明	示例
app_id	string	是	开放平台应用 ID	595f23df
signa	string	是	加密数字签名	BFQEcN3SgZNC4eECvq0LFUPVHvI=
ts	string	是	时间戳	1512041814
task_id	string	是	任务 ID（预处理接口返回值）	4b705edda27a4140b31b462df0033cfa

返回值

成功

{
  "ok": 0,
  "err_no": 0,
  "failed": null,
  "data": "[{\"bg\":\"0\",\"ed\":\"4950\",\"onebest\":\"智能语音技术提供商。\",\"speaker\":\"0\"}]"
}

失败

{
  "ok": -1,
  "err_no": 26601,
  "failed": "非法应用信息",
  "data": null
}

附录

转写结果字段说明

字段名	说明
bg	句子相对于本音频的起始时间，单位为 ms
ed	句子相对于本音频的终止时间，单位为 ms
onebest	句子内容
speaker	说话人编号，从 1 开始，未开启说话人分离时 speaker 都为 0
si	句子标识，相同 si 表示同一句话，从 0 开始注：仅开启分词或者多候选时返回
wordsResultList	分词列表注：仅开启分词或者多候选时返回，且英文暂不支持
alternativeList	多候选列表，按置信度排名注：仅开启分词或者多候选时返回，且英文暂不支持
wordBg	词相对于本句子的起始帧，其中一帧是 10ms 注：仅开启分词或者多候选时返回，且英文暂不支持
wordEd	词相对于本句子的终止帧，其中一帧是 10ms 注：仅开启分词或者多候选时返回，且英文暂不支持
wordsName	词内容注：仅开启分词或者多候选时返回，且英文暂不支持
wc	句子置信度，范围为[0,1] 注：仅开启分词或者多候选时返回，且英文暂不支持
wp	词属性，n 代表普通词，r 代表人名，d 代表数字，m 代表量词，s 代表顺滑词（语气词），t 代表地名&多音字，p 代表标点，g 代表分段标识注：仅开启分词或者多候选时返回

错误码

错误码	错误码描述
0	成功
26000	转写内部通用错误
26100	转写配置文件错误
26101	转写配置文件 app_id/secret_key 为空
26102	转写配置文件 lfasr_host 错误
26103	转写配置文件 file_piece_size 错误
26104	转写配置文件 file_piece_size 建议设置 10M-30M 之间
26105	转写配置文件 store_path 错误，或目录不可读写
26201	转写参数上传文件不能为空或文件不存在
26202	转写参数类型不能为空
26203	转写参数客户端生成签名错误
26301	转写断点续传持久化文件读写错误
26302	转写断点续传文件夹读写错误
26303	转写恢复断点续传流程错误,请见日志
26401	转写上传文件路径错误
26402	转写上传文件类型不支持错误
26403	转写本地文件上传超过限定大小 500M
26404	转写上传文件读取错误
26500	HTTP 请求失败
26501	转写获取版本号接口错误
26502	转写预处理接口错误
26503	转写上传文件接口错误
26504	转写合并文件接口错误
26505	转写获取进度接口错误
26506	转写获取结果接口错误
26600	转写业务通用错误
26601	非法应用信息
26602	任务 ID 不存在
26603	接口访问频率受限（默认 1 秒内不得超过 20 次）
26604	获取结果次数超过限制，最多 100 次
26605	任务正在处理中，请稍后重试
26606	空音频，请检查
26610	请求参数错误
26621	预处理文件大小受限（500M）
26622	预处理音频时长受限（5 小时）
26623	预处理音频格式受限
26625	预处理服务时长不足。您剩余的可用服务时长不足，请移步产品页http://www.xfyun.cn/services/lfasr 进行购买或者免费领取
26631	音频文件大小受限（500M）
26632	音频时长受限（5 小时）
26633	音频服务时长不足。您剩余的可用服务时长不足，请移步产品页http://www.xfyun.cn/services/lfasr 进行购买或者免费领
26634	文件下载失败
26635	文件长度校验失败
26640	文件上传失败
26641	上传分片超过限制
26642	分片合并失败
26643	计算音频时长失败,请检查您的音频是否加密或者损坏
26650	音频格式转换失败,请检查您的音频是否加密或者损坏
26660	计费计量失败
26670	转写结果集解析失败
26680	引擎处理阶段错误

任务状态码

状态 ID	状态描述
0	任务创建成功
1	音频上传完成
2	音频合并完成
3	音频转写中
4	转写结果处理中
5	转写完成
9	转写结果上传完成

语音转写 API 文档 #

接口说明 #

接口要求 #

接口调用流程 #

1、预处理接口 #

概述 #

URL #

请求头 #

参数说明 #

结果说明 #

2、文件分片上传接口 #

概述 #

url #

请求头 #

参数说明 #

signa 生成 #

返回值 #

slice_id 生成代码(python)示例 #

3、合并文件接口 #

概述 #

url #

请求头 #

参数说明 #

返回值 #

4、查询处理进度接口 #

概述 #

url #

请求头 #

参数说明 #

返回值 #

处理流程 #

5、获取结果接口 #

概述 #

url #

请求头 #

参数说明 #

返回值 #

附录 #

转写结果字段说明 #

错误码 #

任务状态码 #

语音转写 API 文档

接口说明

接口要求

接口调用流程

1、预处理接口

概述

URL

请求头

参数说明

结果说明

2、文件分片上传接口

概述

url

请求头

参数说明

signa 生成

返回值

slice_id 生成代码(python)示例

3、合并文件接口

概述

url

请求头

参数说明

返回值

4、查询处理进度接口

概述

url

请求头

参数说明

返回值

处理流程

5、获取结果接口

概述

url

请求头

参数说明

返回值

附录

转写结果字段说明

错误码

任务状态码