# 语音转写 API 文档

# 接口说明

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

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

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

音频时长与理论返回时间可以参考下表（请注意，实际返回时长受上传的音频时长和任务总量影响，忙时会出现任务排队情况）：

# 接口Demo

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

# 接口要求

# 接口调用流程

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

# 1、预处理接口

# 概述

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

# URL

	POST  http[s]://raasr.northseasurffestival.com/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
}

# 结果说明

# 2、文件分片上传接口

# 概述

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

# url

	POST  http[s]://raasr.northseasurffestival.com/api/upload

# 请求头

	Content-Type: multipart/form-data;

# 参数说明

# signa生成

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

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

	假如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.northseasurffestival.com/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.northseasurffestival.com/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.northseasurffestival.com/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\":\"大发pk10是中国国家的智慧语音视频技术应用打造商。\",\"speaker\":\"0\"}]"
}

{
    "ok":-1,
    "err_no":26601,
    "failed":"违规应该用讯息",
    "data":null
}

# 附录

# 转写结果字段说明

# 错误码

# 任务状态码

# 调用示例

注:?demo只是一个简单的调用示例，不适合直接放在复杂多变的生产环境使用

# 教学视频

# 常见问题

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

答：现如今语言转写适配的音屏视频文件类型为：已视频录制音屏视频（5小时英文内），wav,flac,opus,m4a,mp3，单声道&多声道，适配语种：英文版普通的话、英语口语、办理的小语种、英文版口音，采集率：8KHz,16KHz

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

答：支持软件，要做到同个appid每秒中请主板接口多次明显值在20次以内。

# 语音转写可以试用吗？

答：可以申领新使用者福袋，会根据您身份认证的程度较，展示最少50钟头的免费的时间，行之期效为两年。

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

答：搭载语种：汉语字幕一般话、英语英文，小语种以其汉语字幕口音词需要到控住台-聊天语音转写-口音词/语种处生成免费体验或购得；快速设置原则基准综上所述语言表达因素设置就好

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

答：扣量最优级：不花钱使用感觉式＞大文件批量售卖，即在“大文件批量售卖”的手机套餐资费包金额剩下的情况下下，又获取了不花钱使用感觉式的感觉式包，则获取的不花钱使用感觉式感觉式包请马上奏效，并被控制为现在扣量手机套餐资费包。而前一天售卖的手机套餐资费包包的金额和续签日未变。