# 录音文件转写极速版 API 文档

# 接口说明

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

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

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

# 接口Demo

示例demo请点击这里下载。

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

欢迎热心的开发者到讯飞开放平台社区 (opens new window)分享你们的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 中配置以下参数：

示例：

'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="

# 鉴权结果

如果鉴权失败，则根据不同错误类型返回不同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"
}

# 请求参数

# 1、小文件上传

# body请求参数示例

 --9b83bcf71c7e0557482f2aa260bb5a86
Content-Disposition: form-data; name="data";filename=".\audio\demo.wav"
Content-Type: audio/wavRIFFF\x80\x01\x00WAVEfmt\...\x10\x00\x03--9b83bcf71c7e0557482f2aa260bb5a86
Content-Disposition: form-data; name="app_id"your_appid--9b83bcf71c7e0557482f2aa260bb5a86
Content-Disposition: form-data; name="request_id"202201111019--9b83bcf71c7e0557482f2aa260bb5a86

# body请求参数说明

参数名	类型	必传	描述
request_id	string	是	请求唯一标识
app_id	string	是	应用唯一标识
data	file	是	文件上传数据

# 返回参数示例

{
	"code": 0,
	"sid": "ost00010002@dx172fd79467d7a04802",
	"data": {
		"url": "return_url"
	},
	"message": "success"
}

# 返回参数说明

参数名	类型	描述
code	int	错误码，0标识成功
message	string	错误描述
sid	string	会话唯一标识
data.url	string	文件下载地址

# 2、分块上传

# （1）初始化分块信息

# 请求参数示例

{
	"request_id": "202006290840",
	"app_id": "4CC5779A"
}

# 请求参数说明

参数名	类型	必传	描述
request_id	string	是	请求唯一标识
app_id	string	是	用户唯一标识

# 返回参数示例

{
	"code": 0,
	"sid": "ost00010004@dx172fd871c417a04802",
	"data": {
		"upload_id": "return_upload_id"
	},
	"message": "success"
}

# 返回参数说明

参数名	类型	描述
code	int	错误码，0标识成功
message	string	错误描述
sid	string	会话唯一标识
data.upload_id	string	上传唯一标识

# （2）分块上传

# body请求参数示例

 --61ab2ddcdc781408ca565561ee4df66e
Content-Disposition:form-data;name="data";filename=".\audio\1-\xe9\xa9\xac\xe5\x8c\x96\xe8\x85\xbe\xe6\xbc\x94\xe8\xae\xb2.pcm"
Content-Type:application/octet-stream\x00\x005\...\x13\xfb--61ab2ddcdc781408ca565561ee4df66e
Content-Disposition:form-data;name="app_id"your_appid--61ab2ddcdc781408ca565561ee4df66e
Content-Disposition:form-data;name="request_id"202201141107--61ab2ddcdc781408ca565561ee4df66e
Content-Disposition:form-data;name="upload_id"your_return_upload_id--61ab2ddcdc781408ca565561ee4df66e
Content-Disposition:form-data;name="slice_id"23--61ab2ddcdc781408ca565561ee4df66e--

# 请求参数说明

参数名	类型	必传	描述
request_id	string	是	请求唯一标识
app_id	string	是	应用唯一标识
upload_id	string	是	上传唯一标识
slice_id	int	是	分片号
data	file	是	上传数据

# 返回参数示例

{
	"code": 0,
	"sid": "ost00010006@dx172fd8b7afb7a04802",
	"message": "success"
}

# 返回参数说明

参数名	类型	描述
code	int	错误码，0标识成功
sid	string	会话唯一标识
message	string	错误描述

# （3）分块上传完成

# 请求参数示例

{
	"request_id": "202006290849",
	"app_id": "your_appid",
	"upload_id": "your_return_upload_id"
}

# 请求参数说明

参数名	类型	必传	描述
request_id	string	是	请求唯一标识
app_id	string	是	应用唯一标识
upload_id	string	是	上传唯一标识

# 返回参数示例

{
	"code": 0,
	"sid": "ost00010008@dx172fd8fda817a04802",
	"data": {
		"url": "return_url"
	},
	"message": "success"
}

# 返回参数说明

参数名	类型	描述
code	int	错误码，0标识成功
sid	string	会话唯一标识
data.url	string	文件下载地址
message	string	错误描述

# 3、创建任务

# 请求参数示例

{
	"common": {
		"app_id": "your_appid"
	},
	"business": {
		"request_id": "1612345511236963551344",
		"language": "zh_cn",
		"domain": "pro_ost_ed",
		"accent": "mandarin",
		"callback_url": "your_callback_url" //可选字段
	},
	"data": {
		"audio_url": "https://xfyun-seve-dx/19Si······",
		"audio_src": "http",
		"format": "audio/L16;rate=16000",
		"encoding": "raw"
	}
}

# 请求参数说明

参数名	类型	必传	描述
common.appid	string	是	在控制台获取
business.request_id	string	是	客户端用于标记任务的唯一id，最大长度64字符，由客户端保证唯一性，服务回调结果时会包含此参数
business.language	string	是	取值范围：zh_cn
business.domain	string	是	取值范围：pro_ost_ed
business.accent	string	是	口音与 language、domain 参数一起映射具体引擎类型，取值范围：mandarin
business.callback_url	string	否	任务结果回调服务地址，自定义具体值，Java获取示例可参考callback_url java 获取示例 (opens new window)
business.vspp_on	int	否	是否开启说话人分离，默认为0 0：不开启 1：开启注：目前mp3不支持角色分离
business.speaker_num	int	否	说话人个数，默认0： 0：表示盲分非0正数：表示指定的说话人个数
business.output_type	int	否	输出结果类型，默认为0，为0时置信度不生效 0：1best 1：cnlbest 2：多候选（传2需要关掉后处理才生效）
business.postproc_on	int	否	后处理开关，默认1： 1：开启 0：关闭
business.pd	string	否	领域个性化参数: 法院: court 教育: edu 金融: finance 医疗: medical 科技: tech 体育: sport 政府: gov 游戏: game 电商: ecom 汽车: car
business.duration	int	否	音频时长，单位秒
business.enable_subtitle	int	否	字幕文稿功能，1: 字幕场景，0: 文稿场景 (默认)
business.smoothproc	boolean	否	顺滑开关，true表示开启，false表示关闭，默认值为true
business.colloqproc	boolean	否	口语规整开关，true表示开启，false表示关闭，默认值为false
business.language_type	int	否	语言模式开关: 1：自动，中英文混合模式 (默认) 2：中文模式，可识别出简单英文 3：英文模式，只识别出英文 4：纯中文模式，只识别出中文
business.vto	int	否	vad强切控制，单位ms
business.dhw	string	否	会话级热词，多个热词用英文 ',' 分隔。只支持UTF8 编码
data.audio_url	string	是	用于上传转写音频地址
data.audio_src	string	是	音频来源类型，暂时支持http
data.audio_size	int	否	音频文件大小，单位为字节
data.format	string	是	音频的采样率支持16k,audio/L16;rate=16000
data.encoding	string	是	音频数据格式： wav、pcm（传参raw） mp3（传参lame）

# 返回参数示例

{
	"code": 0,
	"message": "success",
	"sid": "ost00620001@dx16c8a2b9cbb5745192",
	"data": {
		"task_id": "1568100557463963551003"
	}
}

# 返回参数说明

参数名	类型	描述
sid	string	每次会话的唯一标识
code	int	错误码，0标识成功
message	string	错误描述
data	object	返回结果
data.task_id	string	本次创建的任务id

# 4、查询任务

# 请求参数示例

{
	"common": {
		"app_id": "your_appid"
	},
	"business": {
		"task_id": "1568100557463963551003"
	}
}

# 请求参数说明

参数名	类型	必传	描述
common.appid	string	是	在控制台获取
business.task_id	string	是	任务唯一标识

# 返回参数示例

{
	"code": 0,
	"data": {
		"force_refresh": "0",
		"result": {
			"file_length": 16462,
			"lattice": [{
				"begin": "0",
				"end": "470",
				"json_1best": {
					"st": {
						"bg": "0",
						"ed": "470",
						"pa": "1242",
						"pt": "reserved",
						"rl": "0",
						"rt": [{
							"nb": "1",
							"nc": "1.0",
							"ws": [{
								"cw": [{
									"w": "听说",
									"wc": "1.0000",
									"wp": "n"
								}],
								"wb": 1,
								"we": 40
							}, {
								"cw": [{
									"w": "。",
									"wc": "0.0000",
									"wp": "p"
								}],
								"wb": 40,
								"we": 40
							}, {
								"cw": [{
									"w": "",
									"wc": "0.0000",
									"wp": "g"
								}],
								"wb": 40,
								"we": 40
							}]
						}],
						"sc": "1.00",
						"si": "5781"
					}
				},
				"lid": "1242",
				"spk": "段落-0"
			}],
			"lattice2": [{
				"begin": "0",
				"end": "470",
				"json_1best": {
					"st": {
						"bg": "0",
						"ed": "470",
						"pa": "1242",
						"pt": "reserved",
						"rl": "0",
						"rt": [{
							"nb": "1",
							"nc": "1.0",
							"ws": [{
								"cw": [{
									"w": "听说",
									"wc": "1.0000",
									"wp": "n"
								}],
								"wb": 1,
								"we": 40
							}, {
								"cw": [{
									"w": "。",
									"wc": "0.0000",
									"wp": "p"
								}],
								"wb": 40,
								"we": 40
							}, {
								"cw": [{
									"w": "",
									"wc": "0.0000",
									"wp": "g"
								}],
								"wb": 40,
								"we": 40
							}]
						}],
						"sc": "1.00",
						"si": "5781"
					}
				},
				"lid": "1242",
				"spk": "段落-0"
			}]
		},
		"task_id": "220114135557737430397630",
		"task_status": "4",
		"task_type": "distribute_task"
	},
	"message": "success",
	"sid": "ost000eda43@dx17e572841a56f22902"
}

# 返回参数说明

参数名	类型	描述
sid	string	每次会话的唯一标识
code	int	错误码，0标识成功
message	string	错误描述
data	object	查询结果
data.task_id	string	本次查询的任务id
data.task_status	string	任务状态，3和4状态表示存在识别结果： 1：待处理 2：处理中 3：处理完成 4：回调完成
data.task_type	string	任务类型
data.force_refresh	string	0：不需要强制刷新 1：需要强制刷新可以忽略，目前未启用
data.result	string	识别内容
data.result.file_length	int	音频长度（字节）
data.result.lattice	array	经过后处理的识别结果（标记词的属性或经过口语规整，顺滑后的结果，与传参相关）
data.result.lattice2	array	后处理前的识别结果（原始结果，不区分词的属性，即没有口语规整、顺滑等效果）
data.result.lattice.begin	string	开始时间
data.result.lattice.end	string	结束时间
data.result.lattice.json_1best	object	转写引擎输出结果
data.result.lattice.lid	string	段落标识，相同lid表示同一段落，从0开始，随段落数增加
data.result.lattice.spk	string	说话人编号，后面数字与角色值一致
data.result.lattice.json_1best.st	object	句子
data.result.lattice.json_1best.st.bg	string	句子开始的位置，单位ms
data.result.lattice.json_1best.st.ed	string	句子结束的位置，单位ms
data.result.lattice.json_1best.st.pa	string	段落，注：开cn多候选时没有这个字段符号
data.result.lattice.json_1best.st.pt	string	保留字段
data.result.lattice.json_1best.st.rl	string	说话人角色
data.result.lattice.json_1best.st.sc	string	真实句子置信度，等于词语置信度的平均(不包含标点)
data.result.lattice.json_1best.st.si	string	vad的ID号
data.result.lattice.json_1best.st.rt	array	开始输出识别结果
data.result.lattice.json_1best.st.rt.nb	string	句子number数，目前均是1，暂无实际意义
data.result.lattice.json_1best.st.rt.nc	string	句子置信度，目前均是1，暂无实际意义
data.result.lattice.json_1best.st.rt.ws	array	表示开始输出词语识别结果
data.result.lattice.json_1best.st.rt.ws.cw	array	词语候选识别结果
data.result.lattice.json_1best.st.rt.ws.cw.w	string	识别结果
data.result.lattice.json_1best.st.rt.ws.cw.wc	string	词语的置信度
data.result.lattice.json_1best.st.rt.ws.cw.wp	string	词语的属性 n：表示正常词 s：表示顺滑 p：表示标点 g：表示分段
data.result.lattice.json_1best.st.rt.ws.wb	string	词语开始的帧数（注一帧10ms），位置是相对bg
data.result.lattice.json_1best.st.rt.ws.we	string	词语结束的帧数（注一帧10ms），位置是相对bg

# 错误码

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

# 调用示例

录音文件转写极速版 demo java语言 (opens new window)

录音文件转写极速版 demo python语言 (opens new window)

注：其他开发语言请参照接口调用流程进行开发，也欢迎热心的开发者到讯飞开放平台社区 (opens new window) 分享你们的demo。

# 常见问题

# 录音文件转写极速版的主要功能是什么？

答：快速地将长段音频（5小时以内）数据转换成文本数据。

# 录音文件转写极速版支持什么语言？

答：中文、英文、中英文混合。

# 录音文件转写极速版支持什么应用平台？

答：目前支持WebAPI应用平台。

# 录音文件转写极速版对音频有什么要求吗？

答：采样率16k、位长16bit、单声道的wav/pcm/mp3音频。

在这篇文章中：

# 录音文件转写极速版 API 文档

# 接口说明

# 接口Demo

# 接口要求

# 接口调用流程

# 鉴权认证

# 鉴权方法

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

# 2、参数生成规则

# 鉴权结果

# 请求参数

# 1、小文件上传

# body请求参数示例

# body请求参数说明

# 返回参数示例

# 返回参数说明

# 2、分块上传

# （1）初始化分块信息

# 请求参数示例

# 请求参数说明

# 返回参数示例

# 返回参数说明

# （2）分块上传

# body请求参数示例

# 请求参数说明

# 返回参数示例

# 返回参数说明

# （3）分块上传完成

# 请求参数示例

# 请求参数说明

# 返回参数示例

# 返回参数说明

# 3、创建任务

# 请求参数示例

# 请求参数说明

# 返回参数示例

# 返回参数说明

# 4、查询任务

# 请求参数示例

# 请求参数说明

# 返回参数示例

# 返回参数说明

# 错误码

# 调用示例

# 常见问题

# 录音文件转写极速版的主要功能是什么？

# 录音文件转写极速版支持什么语言？

# 录音文件转写极速版支持什么应用平台？

# 录音文件转写极速版对音频有什么要求吗？