大模型中文语音识别 API 文档

一、接口说明

大模型中文语音识别能力，将中文短音频(≤60秒)精准识别成文字，实时返回文字结果，真实还原语音内容。

二、接口Demo

部分开发语言Demo如下，其他开发语言请参照文档进行开发，欢迎大家到车联AI-Saas平台社区交流集成经验。

大模型中文语音识别 Demo java语言
 大模型中文语音识别 Demo python语言

三、接口要求

内容	说明
请求协议	ws[s]（为提高安全性，强烈推荐wss）
请求地址	中文语音地址：ws[s]: //iat.xf-yun.com/v1
接口鉴权	签名机制，详情请参照下方接口鉴权
字符编码	UTF-8
响应格式	统一采用JSON格式
开发语言	任意，只要可以向车联云服务发起HTTP请求的均可
音频属性	采样率16k或8K、位长16bit、单声道
音频格式	pcm、mp3
音频长度	最长60s

四、接口鉴权

鉴权方法

通过在请求地址后面加上鉴权相关参数的方式。示例url：

wss://iat-api.xfyun.cn/v2/iat?authorization=YXBpX2tleT0ia2V5eHh4eHh4eHg4ZWUyNzkzNDg1MTlleHh4eHh4eHgiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iSHAzVHk0WmtTQm1MOGpLeU9McFFpdjlTcjVudm1lWUVIN1dzTC9aTzJKZz0i&date=Wed%2C%2010%20Jul%202019%2007%3A35%3A43%20GMT&host=iat-api.xfyun.cn

鉴权参数：

参数	类型	必须	说明	示例
host	string	是	请求主机	iat-api.xfyun.cn
date	string	是	当前时间戳，RFC1123格式	Wed, 10 Jul 2019 07:35:43 GMT
authorization	string	是	使用base64编码的签名相关信息(签名基于hmac-sha256计算)	参考下方authorization参数生成规则

· date参数生成规则

date必须是UTC+0或GMT时区，RFC1123格式(Wed, 10 Jul 2019 07:35:43 GMT)。
服务端会对Date进行时钟偏移检查，最大允许300秒的偏差，超出偏差的请求都将被拒绝。

· authorization参数生成规则

1）获取接口密钥APIKey 和 APISecret。
在车联AI-Saas平台控制台，创建WebAPI平台应用并添加语音听写（流式版）服务后即可查看，均为32位字符串。

2）参数authorization base64编码前（authorization_origin）的格式如下。

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

其中 api_key 是在控制台获取的APIKey，algorithm 是加密算法（仅支持hmac-sha256），headers 是参与签名的参数（见下方注释）。
signature 是使用加密算法对参与签名的参数签名后并使用base64编码的字符串，详见下方。

注： headers是参与签名的参数，请注意是固定的参数名（"host date request-line"），而非这些参数的值。

3）signature的原始字段(signature_origin)规则如下。

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

host: $host\ndate: $date\n$request-line

假设

请求url = wss://iat-api.xfyun.cn/v2/iat
date = Wed, 10 Jul 2019 07:35:43 GMT

那么 signature原始字段(signature_origin)则为：

host: iat-api.xfyun.cn
date: Wed, 10 Jul 2019 07:35:43 GMT
GET /v2/iat HTTP/1.1

4）使用hmac-sha256算法结合apiSecret对signature_origin签名，获得签名后的摘要signature_sha。

signature_sha=hmac-sha256(signature_origin,$apiSecret)

其中 apiSecret 是在控制台获取的APISecret

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

signature=base64(signature_sha)

假设

APISecret = secretxxxxxxxx2df7900c09xxxxxxxx
date = Wed, 10 Jul 2019 07:35:43 GMT

则signature为

signature=Hp3Ty4ZkSBmL8jKyOLpQiv9Sr5nvmeYEH7WsL/ZO2Jg=

6）根据以上信息拼接authorization base64编码前（authorization_origin）的字符串，示例如下。

api_key="keyxxxxxxxx8ee279348519exxxxxxxx", algorithm="hmac-sha256", headers="host date request-line", signature="Hp3Ty4ZkSBmL8jKyOLpQiv9Sr5nvmeYEH7WsL/ZO2Jg="

注： headers是参与签名的参数，请注意是固定的参数名（"host date request-line"），而非这些参数的值。

7）最后再对authorization_origin进行base64编码获得最终的authorization参数。

authorization = base64(authorization_origin)
示例：
authorization=YXBpX2tleT0ia2V5eHh4eHh4eHg4ZWUyNzkzNDg1MTlleHh4eHh4eHgiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iSHAzVHk0WmtTQm1MOGpLeU9McFFpdjlTcjVudm1lWUVIN1dzTC9aTzJKZz0i

五、数据传输接收与请求、返回示例

1、数据传输接收

握手成功后客户端和服务端会建立Websocket连接，客户端通过Websocket连接可以同时上传和接收数据。
当服务端有识别结果时，会通过Websocket连接推送识别结果到客户端。

发送数据时，如果间隔时间太短，可能会导致引擎识别有误。
建议每次发送音频间隔40ms，每次发送音频字节数（即java示例demo中的frameSize）为一帧音频大小的整数倍。

//连接成功，开始发送数据
int frameSize = 1280; //每一帧音频大小的整数倍，请注意不同音频格式一帧大小字节数不同，可参考下方建议
int intervel = 40;
int status = 0;  // 音频的状态
try (FileInputStream fs = new FileInputStream(file)) {
    byte[] buffer = new byte[frameSize];
    // 发送音频

我们建议：未压缩的PCM格式，每次发送音频间隔40ms，每次发送音频字节数1280B；

2、请求json示例

第一帧数据：

{
  "header": {
    "app_id": "your_appid",
    "status": 0
  },
  "parameter": {
    "iat": {
      "domain": "slm",
      "language": "zh_cn",
      "accent": "mandarin",
      "eos": 6000,
      "vinfo": 1,
      "dwa": "wpgs",
      "result": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  },
  "payload": {
    "audio": {
      "encoding": "raw",
      "sample_rate": 16000,
      "channels": 1,
      "bit_depth": 16,
      "seq": 1,
      "status": 0,
      "audio": "AAAAAP..."
    }
  }
}

中间帧数据：

{
  "header": {
    "app_id": "your_appid",
    "status": 1
  },
  "payload": {
    "audio": {
      "encoding": "raw",
      "sample_rate": 16000,
      "channels": 1,
      "bit_depth": 16,
      "seq": 2,
      "status": 1,
      "audio": "AAAAAA..."
    }
  }
}

最后一帧数据：

{
  "header": {
    "app_id": "your_appid",
    "status": 2
  },
  "payload": {
    "audio": {
      "encoding": "raw",
      "sample_rate": 16000,
      "channels": 1,
      "bit_depth": 16,
      "seq": 591,
      "status": 2,
      "audio": ""
    }
  }
}

3、返回json示例

第一帧返回数据示例：

{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "iat000e0044@hu18f5b16b0330324...",
    "status": 0
  }
}

中间帧返回数据示例：

{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "iat000e0044@hu18f5b16b033032...",
    "status": 1
  },
  "payload": {
    "result": {
      "compress": "raw",
      "encoding": "utf8",
      "format": "json",
      "seq": 2,
      "status": 1,
      "text": "eyJzbiI6Miwib..."
    }
  }
}

最后一帧返回数据示例：

{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "iat000e0044@hu18f5b16b033032...",
    "status": 2
  },
  "payload": {
    "result": {
      "compress": "raw",
      "encoding": "utf8",
      "format": "json",
      "seq": 76,
      "status": 2,
      "text": "eyJzbiI6NzYs..."
    }
  }
}

六、参数说明

1、请求参数说明

参数名	类型	必传	描述
header	object	是	用于上传平台参数
header.app_id	string	是	在平台申请的appid信息
header.status	int	是	音频传输状态 0:首帧 1：中间帧 2:最后一帧
parameter	object	是	用于上传服务特性参数
parameter.iat	object	是	服务名称，大模型中文语音识别
parameter.iat.domain	string	是	指定访问的领域 slm
parameter.iat.language	string	是	语种 zh_cn
parameter.iat.accent	string	是	方言 mandarin（代表普通话）
parameter.iat.eos	int	否	静音多少秒停止识别如6000毫秒
parameter.iat.vinfo	int	否	句子级别帧对齐
parameter.iat.dwa	string	否	流式识别PGS 返回速度更快，仅中文支持
parameter.iat.result	obejct	否	响应数据字段
payload	object	是	请求数据携带
payload.audio	object	是	音频数据模块
payload.audio.encoding	string	否	音频编码 raw或lame
payload.audio.sample_rate	int	否	音频采样率 16000, 8000
payload.audio.channels	int	否	音频声道 1
payload.audio.bit_depth	int	否	音频位深 16
payload.audio.seq	int	否	数据序号 0-999999
payload.audio.status	int	否	取值范围为：0（开始）、1（继续）、2（结束）
payload.audio.audio	string	是	音频数据base64 音频时长不要超过60秒

2、返回参数说明

参数名	类型	描述
header	object	协议头部
header.message	string	描述信息
header.code	int	返回码 0表示会话调用成功（并不一定表示服务调用成功，服务是否调用成功以text字段中的ret为准）其它表示会话调用异常
header.sid	string	本次会话id
header.status	int	数据状态 0:开始, 1:继续, 2:结束
payload	object	数据段，用于携带响应的数据
payload.result.compress	string	文本压缩格式
payload.result.encoding	string	文本编码
payload.result.format	string	文本格式
payload.result.seq	int	数据序号 0-999999
payload.result.status	int	0:开始, 1:继续, 2:结束
payload.result.text	string	听写数据文本 base64编码

text字段base64解码后参数说明请：

参数	类型	描述
sn	int	返回结果的序号
ls	bool	是否是最后一片结果
bg	int	保留字段，无需关心
ed	int	保留字段，无需关心
ws	array	听写结果
ws.bg	int	起始的端点帧偏移值，单位：帧（1帧=10ms）注：以下两种情况下bg=0，无参考意义： 1)返回结果为标点符号或者为空；2)本次返回结果过长。
ws.cw	array	中文分词
ws.cw.w	string	字词
ws.cw.其他字段 sc/wb/wc/we/wp	int/string	均为保留字段，无需关心。如果解析sc字段，建议float与int数据类型都做兼容

七、常见问题

大模型中文语音识别与语音听写的区别？

答：大模型中文语音识别基于大模型进行的训练，数据量更丰富，听写效果上限更高，未来发展性更强。

大模型中文语音识别支持多少分钟的音频识别？

答：支持1分钟以内的音频识别。

# 大模型中文语音识别 API 文档

# 一、接口说明

# 二、接口Demo

# 三、接口要求

# 四、接口鉴权

# 鉴权方法

# 五、数据传输接收与请求、返回示例

# 1、数据传输接收

# 2、请求json示例

# 3、返回json示例

# 六、参数说明

# 1、请求参数说明

# 2、返回参数说明

# 七、常见问题

# 大模型中文语音识别与语音听写的区别？

# 大模型中文语音识别支持多少分钟的音频识别？