极速语音转写 API 文档

接口说明

极速语音转写（Speed Transcription）基于深度全序列卷积神经网络，将长段音频（5小时以内）数据转换成文本数据，为信息处理和数据挖掘提供基础。极速语音转写最快可以达到1小时音频转写，完成仅耗时20秒。

极速语音转写是已录制音频（非实时）快速转写成文字，音频文件上传成功后进入等待队列，待转写成功后用户即可获取结果，音频时长与理论返回时间可以参考：音频时长1小时极速语音转写耗时1分钟左右返回。其他时长的，可以等比例替换。如果很短的音频，考虑到系统调度等因素，也要20秒左右。（请注意，实际返回时长受上传的音频时长和任务总量影响，忙时会出现任务排队情况）。另外，为使转写服务更加通畅，请尽量转写5分钟以上的音频文件。

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

#接口Demo

示例demo请点击 这里 下载。

demo 覆盖部分语言，其他语言参照下方接口文档进行开发。

欢迎热心的开发者到讯飞开放平台社区 分享你们的demo。

#接口要求

集成同声传译API时，需按照以下要求。

内容	说明
传输方式	http[s]（为提高安全性，强烈推荐https）
请求地址	1、小文件上传（小于30M）https://upload-ost-api.xfyun.cn/file/upload 2、大文件分块上传 （1）初始化分块信息 https://upload-ost-api.xfyun.cn/file/mpupload/init （2）分块上传 https://upload-ost-api.xfyun.cn/file/mpupload/upload （3）分块上传完成 https://upload-ost-api.xfyun.cn/file/mpupload/complete 3、创建任务 https://ost-api.xfyun.cn/v2/ost/pro_create 4、查询任务 https://ost-api.xfyun.cn/v2/ost/query
请求行	POST /xxx/xxx HTTP/1.1 (/xxx/xxx根据请求地址替换，如/file/upload或/v2/ost/pro_create等)
接口鉴权	签名机制，详情请参照下方鉴权认证
字符编码	UTF-8
响应格式	统一采用JSON格式
开发语言	任意，只要可以向讯飞云服务发起HTTP请求的均可
音频属性	采样率16k、位长16、单声道
音频格式	wav/pcm/mp3
音频大小	不超过500M
音频时长	不超过5小时，建议5分钟以上
语言种类	中文、英文、中英文混合
转写结果保存时长	7天

#接口调用流程

• 通过接口密钥基于hmac-sha256计算签名。详见下方 鉴权认证 。
• 将请求参数以及数据放在Http Request Body中，以POST表单的形式提交，详见下方 请求参数 。
• 向服务器端发送Http请求后，接收服务器端的返回结果。

#鉴权认证

在调用业务接口时，请求方需要对请求进行签名，服务端通过签名来校验请求的合法性。

#鉴权方法

通过在请求地址后面加上鉴权相关参数的方式， 请注意影响鉴权结果的值有url、apiSecret、apiKey、date，如果调试鉴权，请务必按照示例中给的值进行调试， 具体在 Http Request Header 中配置以下参数：

#1、Header参数描述，请以键值对形式传递

示例：

'host': 'upload-ost-api.xfyun.cn' 
'date': 'Wed, 29 Dec 2021 07:06:31 GMT' 
'authorization': 'api_key="91205afe0d17e38c61be35fca346503c", algorithm="hmac-sha256", headers="host date request-line digest", signature="rbzT4wmZc050+52AtnSNWfcmRMPFHdzThqnR0cE4QcY="'
'digest': 'SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU='
'content-type': 'multipart/form-data; boundary=a0df7967173af147fe3ae65068b9b622'

Header参数说明：

参数	类型	必须	说明	示例
host	string	是	请求主机，根据请求url不同而不同	upload-ost-api.xfyun.cn
date	string	是	当前时间戳，RFC1123格式("EEE, dd MMM yyyy HH:mm:ss z")	Wed, 29 Dec 2021 07:06:31 GMT
digest	string	是	body 的摘要，用sha256计算,计算方法为 Digest="SHA256="+base64(sha256(body))	SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
authorization	string	是	鉴权参数，具体构建方法如下	详细生成规则参考下方
content-type	string	是	互联网媒体类型	有文件上传multipart/form-data 无文件上传application/json

#2、参数生成规则

(1) host生成规则，例如：
https://upload-ost-api.xfyun.cn/file/upload 对应的Host为upload-ost-api.xfyun.cn
https://ost-api.xfyun.cn/v2/ost/query 对应的Host为ost-api.xfyun.cn
(2) date生成规则：
date必须是UTC+0或GMT时区，RFC1123格式(Wed, 05 Jan 2022 09:29:14 GMT)。
服务端会对date进行时钟偏移检查，最大允许300秒的偏差，超出偏差的请求都将被拒绝。
(3) digest生成规则：
计算规则固定，不受任何参数值的影响，Java计算示例如下：

byte[] tempBytes=MessageDigest.getInstance("SHA-256").digest();
Digest="SHA256="+ Base64.getEncoder().encodeToString(tempBytes);
最终：
Digest="SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="

(4) authorization生成规则：
Authorization的格式如下，其需要用到signature的值：
注：headers是参与签名的参数，请注意是固定的参数名（"host date request-line"），而非这些参数的值。

api_key="$api_key",algorithm="hmac-sha256",headers="host date request-line digest",signature="$signature"

1）signature生成规则：signature原始字段由 host，date，request-line、Digest四个参数按照格式拼接成，拼接的格式为(\n为换行符,’:’后面有一个空格)：

host: $host\ndate: $date\n$request-line\ndigest: $digest
假设以小文件上传url为例：
请求url = "https://upload-ost-api.xfyun.cn/file/upload"
date = "Wed, 05 Jan 2022 09:29:14 GMT"
那么最终signature原始字段(signature_origin)示例如下：
-----------------------------------------------
host: upload-ost-api.xfyun.cn
date: Wed, 05 Jan 2022 09:29:14 GMT
POST /file/upload HTTP/1.1
digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

2）使用hmac-sha256算法，结合APISecret（讯飞开放平台-控制台获取）对signature_origin进行签名，获得签名后的摘要signature_sha。

假设APISecret="apisecretXXXXXXXXXXXXXXXXXXXXXXX"
则：
signature_sha=hmac-sha256(signature_origin,$apiSecret)

3）使用base64编码对signature_sha进行编码，获得最终的signature

signature=base64(signature_sha)
示例：bsLfoGMgZJkoDTuytkPra2NGLS/jzTMHOwbLZusw65A=

4）根据以上信息拼接authorization的字符串，其中APIKey（讯飞开放平台-控制台获取），示例如下。

假设api_key="apikeyXXXXXXXXXXXXXXXXXXXXXXXXXX"
则authorization最终示例如下：
api_key="apikeyXXXXXXXXXXXXXXXXXXXXXXXXXX", algorithm="hmac-sha256", headers="host date request-line digest", signature="bsLfoGMgZJkoDTuytkPra2NGLS/jzTMHOwbLZusw65A="

错误码

错误码	错误描述	处理策略
10107	自定音频编码字段错误	请检查encoding的传值是否规范
10303	参数值传递不规范	请检查传参值是否有误
10043	音频解码失败	请检查所传的音频是否与encoding字段描述的编码格式对应
20304	静音音频、音频格式与传参不匹配、音频格式不符	检查音频是否为16k、16bit单声道音频
10043	使用音频格式与编码格式encoding没有按文档描述对应	参照data.encoding参数取值进行比对

#鉴权结果

如果鉴权失败，则根据不同错误类型返回不同HTTP Code状态码，同时携带错误描述信息，详细错误说明如下：

HTTP Code	说明	错误描述信息	解决方法
401	缺少authorization参数	{"message":"Unauthorized"}	检查是否有authorization参数，详情见authorization参数详细生成规则
401	签名参数解析失败	{“message”:”HMAC signature cannot be verified”}	检查签名的各个参数是否有缺失是否正确，特别确认下复制的api_key是否正确
401	签名校验失败	{“message”:”HMAC signature does not match”}	签名验证失败，可能原因有很多。 1. 检查api_key,api_secret 是否正确。 2.检查计算签名的参数host，date，request-line是否按照协议要求拼接。 3. 检查signature签名的base64长度是否正常(正常44个字节)。
403	时钟偏移校验失败	{“message”:”HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication”}	检查服务器时间是否标准，相差5分钟以上会报此错误

时钟偏移校验失败示例：

HTTP/1.1 403 Forbidden
Date: Mon, 30 Nov 2020 02:34:33 GMT
Content-Length: 116
Content-Type: text/plain; charset=utf-8
{
    "message": "HMAC signature does not match, a valid date or x-date header is required for HMAC Authentication"
}