# 语音转写 API 文档

# 接口说明

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

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

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

# 接口Demo

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

# 接口要求

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

# 接口调用流程

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

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

通用返回说明：

# 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

# 参数说明

注：

	标准版和电话版本的已经合并，现在购买的都是标准版的订单，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;

# 参数说明

# 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

# 参数说明

# 返回值

成功

{
    "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

# 参数说明

# 返回值

成功

{
    "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

# 参数说明

# 返回值

成功

{
    "ok":0,
    "err_no":0,
    "failed":null,
    "data":"[{\"bg\":\"0\",\"ed\":\"4950\",\"onebest\":\"科大讯飞是中国的智能语音技术提供商。\",\"speaker\":\"0\"}]"
}

失败

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

# 附录

# 转写结果字段说明

# 错误码

# 任务状态码

# 调用示例

语音转写demo python3语言

语音转写demo java语言

语音转写demo nodejs语言

# 教学视频

语音转写技术入门系列课

语音转写WebAPI接口接入实战

# 常见问题

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

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

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

答：支持，要保证同一个appid每秒请求接口次数最大值在20次以下。

# 语音转写可以试用吗？

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

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

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

# 语音转写的套餐扣费顺序是怎样的？

答：扣量优先级：免费试用＞批量购买，即在“批量购买”的套餐额度剩余的情况下，又领取了免费试用的体验包，则领取的免费试用体验包立即生效，并被设定为当前扣量套餐。而之前购买的套餐包的额度和到期日不变。