# 语音转写 API 文档

# 接口说明

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

转写的是已录制音频(非实时),音频文件上传成功后进入等待队列,待转写成功后用户即可获取结果,返回结果时间受音频时长以及排队任务量的影响。 如遇转写耗时比平时延长,大概率表示当前时间段出现转写高峰,请耐心等待即可,我们承诺有效任务耗时最大不超过12小时,详情请参考SLA协议
另外,为使转写服务更加通畅,请尽量转写5分钟以上的音频文件,上传大量的短音频易引起网络和服务器资源紧张,从而导致任务排队积压。

该接口是通过REST API的方式给开发者提供一个通用的HTTP接口,基于该接口,开发者可以获取开发平台的语音转写能力,方便开发者使用自己熟悉的编程语言快速集成。

# 接口Demo

示例demo请点击 这里 下载。
目前仅提供部分开发语言的demo,其他语言请参照下方接口文档进行开发。
也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。

# 接口要求

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

内容 说明
请求协议 http[s](为提高安全性,强烈推荐https)
请求地址 http[s]: //raasr.xfyun.cn/api/xxx
注:服务器IP不固定,为保证您的接口稳定,请勿通过指定IP的方式调用接口,使用域名方式调用
请求方式 POST
接口鉴权 签名机制,详见下方[2、文件分片上传接口]
字符编码 UTF-8
响应格式 统一采用JSON格式
开发语言 任意,只要可以向讯飞云服务发起HTTP请求的均可
音频属性 采样率16k或8k、位长8bits或16bits、单声道&多声道
音频格式 wav/flac/opus/m4a/mp3
音频大小 不超过500M
音频时长 不超过5小时,建议5分钟以上
语言种类 中文普通话、英文
转写结果保存时长 30天
获取结果次数 不得超过100次
SLA保障时长 返回时长最大不超过12小时,赔偿标准等详情请参考SLA协议

# 接口调用流程

转写 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  http[s]://raasr.xfyun.cn/api/prepare

# 请求头

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

# 参数说明

参数 类型 必须 说明 示例
app_id string 讯飞开放平台应用ID 595f23df
signa string 加密数字签名(基于HMACSHA1算法,可参考实时转写生成方式或页面下方demo) BFQEcN3SgZNC4eECvq0LFUPVHvI=
ts string 当前时间戳,从1970年1月1日0点0分0秒开始到现在的秒数 1512041814
file_len string 文件大小(单位:字节) 160044
file_name string 文件名称(带后缀) lfasr_audio.wav
slice_num int 文件分片数目(建议分片大小为10M,若文件<10M,则slice_num=1) 1
lfasr_type string 转写类型,默认 0
0: (标准版,格式: wav,flac,opus,mp3,m4a)
2: (电话版,已取消)
0
has_participle string 转写结果是否包含分词信息 false或true, 默认false
max_alternatives string 转写结果中最大的候选词个数 默认:0,最大不超过5
speaker_number string 发音人个数,可选值:0-10,0表示盲分
:发音人分离目前还是测试效果达不到商用标准,如测试无法满足您的需求,请慎用该功能。
默认:2(适用通话时两个人对话的场景)
has_seperate string 转写结果中是否包含发音人分离信息 false或true,默认为false
has_sensitive string 是否需要对转写结果进行敏感词检测 false或true, 默认:false
sensitive_type string 敏感词检测类型 需要进行敏感词检测(has_sensitive为true)时必传,0(默认词库)或1(自定义敏感词)
keywords string 自定义的敏感词 敏感词检测类型为1时必传,格式:科大讯飞,语音转写(每个词用英文逗号分割,整个字符串长度不超过256)
language string 语种
cn:中文(默认)
en:英文(英文不支持热词)
cn

注:

	标准版和电话版本的已经合并,现在购买的都是标准版的订单,lfasr_type传0即可;
	发音人分离可通过"has_seperate=true"和"speaker_number=个数"来配置。

# 返回值

成功

{
    "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 句子内容
si 句子标识,相同si表示同一句话,从0开始
speaker 说话人编号,从1开始,未开启说话人分离时speaker都为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 转写结果上传完成

# 调用示例

语音转写demo python3语言

语音转写demo java语言

# 教学视频

教学视频

# 常见问题

# 语音转写支持哪些音频格式?

答:目前语音转写支持的音频格式为:已录制音频(5小时内),wav,flac,opus,m4a,mp3,单声道&多声道,支持语种:中文普通话、英语,采样率:8KHz,16KHz

# 语音转写支不支持并发?

答:支持

# 语音转写可以试用吗?

答:平台免费赠送的时长为5小时,供开发者测试使用,每个账户限领取1次。有效期为自生效日起30天。

# 语音转写支持什么语言?

答:支持语种:中文普通话、英语;设置方式参考上述语言参数切换即可