# 语音听写（流式版）WebAPI 文档

# 接口说明

语音听写流式接口，用于1分钟内的即时语音转文字技术，支持实时返回识别结果，达到一边上传音频一边获得识别文本的效果。
高阶效果-动图较正今天手机免费开放政策！个小语种已更新！

动态修正：可到这里 动态修正效果 (opens new window) 在线体验

• 未开启动态修正：实时返回识别结果，每次返回的结果都是对之前结果的追加；
• 开启动态修正：实时返回识别结果，每次返回的结果有可能是对之前结果的追加，也有可能是要替换之前某次返回的结果（即修正）；
• 开启动态修正，相较于未开启，返回结果的颗粒度更小，视觉冲击效果更佳；
• 使用动态修正功能需到控制台-流式听写-高级功能处点击开通，并设置相应参数方可使用，参数设置方法详见 业务参数说明 ；
• 动态修正功能仅 中文 支持；
• 未开启与开启返回的结果格式不同，详见 动态修正返回结果 ；

小语种

• 支持的语种请到语音听写 (opens new window)页面或控制台查看；
• 使用少数民族语言和小语种时，URL和中英文URL不同，详见 接口要求 ；
• 小语种参数设置方法详见 业务参数说明 ；

原WebAPI平民固件版本的接口方式方式(http[s]: //api.northseasurffestival.com/v1/service/v1/iat) 都已经不再针对盛开，都已经用到WebAPI平民固件版本的的用户名仍可用到，的同时也欢迎会感觉新板普鲁士蓝染色接口方式方式并快速搞定转移~

# 接口Demo

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

# 接口要求

# 接口调用流程

• 通过接口密钥基于hmac-sha256计算签名，向服务器端发送Websocket协议握手请求。详见下方 接口鉴权 。
• 握手成功后，客户端通过Websocket连接同时上传和接收数据。数据上传完毕，客户端需要上传一次数据结束标识。详见下方 接口数据传输与接收 。
• 接收到服务器端的结果全部返回标识后断开Websocket连接。

注： Websocket使用注意事项如下

1. 服务端支持的websocket-version 为13，请确保客户端使用的框架支持该版本。
2. 服务端返回的所有的帧类型均为TextMessage，对应于原生websocket的协议帧中opcode=1，请确保客户端解析到的帧类型一定为该类型，如果不是，请尝试升级客户端框架版本，或者更换技术框架。
3. 如果出现分帧问题，即一个json数据包分多帧返回给了客户端，导致客户端解析json失败。出现这种问题大部分情况是客户端的框架对websocket协议解析存在问题，如果出现请先尝试升级框架版本，或者更换技术框架。
4. 客户端会话结束后如果需要关闭连接，尽量保证传给服务端的错误码为websocket错误码1000（如果客户端框架没有提供关闭时传错误码的接口。则无需关注本条）。

# 白名单

默认关闭IP白名单，即该服务不限制调用IP。
在调用该业务接口时

• 若关闭IP白名单，接口认为IP不限，不会校验IP。
• 若打开IP白名单，则服务端会检查调用方IP是否在讯飞开放平台配置的IP白名单中，对于没有配置到白名单中的IP发来的请求，服务端会拒绝服务。

• 在 控制台-相应服务的IP白名单处编辑，保存后五分钟左右生效。
• 不同Appid的不同服务都需要分别设置IP白名单。
• IP白名单需设置为外网IP，请勿设置局域网IP。
• 如果握手阶段返回{"message":"Your IP address is not allowed"}，则表示由于IP白名单配置有误或还未生效，服务端拒绝服务。

# 接口鉴权

在握手阶段，请求方需要对请求进行签名，服务端通过签名来校验请求的合法性。

# 鉴权方法

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

· date参数生成规则

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

· authorization参数生成规则

1）获取接口密钥APIKey 和 APISecret。
在讯飞开放平台控制台，创建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.northseasurffestival.com/v2/iat
date = Wed, 10 Jul 2019 07:35:43 GMT

host: iat-api.northseasurffestival.com
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

signature=base64(signature_sha)

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

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"），而非这些参数的值。

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

# 鉴权url示例(golang)

    //@hosturl :  like  wss://iat-api.northseasurffestival.com/v2/iat
    //@apikey : apiKey
    //@apiSecret : apiSecret
    func assembleAuthUrl(hosturl string, apiKey, apiSecret string) string {
        ul, err := url.Parse(hosturl)
        if err != nil {
            fmt.Println(err)
        }
        //鉴名的时间
        date := time.Now().UTC().Format(time.RFC1123)
        //通过手写签名的字符串 host ,date, request-line
        signString := []string{"host: " + ul.Host, "date: " + date, "GET " + ul.Path + " HTTP/1.1"}
        //结合鉴名空格符串
        sgin := strings.Join(signString, "\n")
        //署名结果显示
        sha := HmacWithShaTobase64("hmac-sha256", sgin, apiSecret)
        //在校园营销推广活动的环节之中所构建中请因素 这时不可以urlencoding
        authUrl := fmt.Sprintf("api_key=\"%s\", algorithm=\"%s\", headers=\"%s\", signature=\"%s\"", apiKey,
            "hmac-sha256", "host date request-line", sha)
        //将要求基本参数动用base64项目编码
        authorization:= base64.StdEncoding.EncodeToString([]byte(authUrl))
        v := url.Values{}
        v.Add("host", ul.Host)
        v.Add("date", date)
        v.Add("authorization", authorization)
        //将商品代码后的字段串url encode后增加到url后
        callurl := hosturl + "?" + v.Encode()
        return callurl
    }

# 鉴权结果

    HTTP/1.1 401 Forbidden
    Date: Thu, 06 Dec 2018 07:55:16 GMT
    Content-Length: 116
    Content-Type: text/plain; charset=utf-8
    {
        "message": "HMAC signature does not match"
    }

# 接口数据传输与接收

握手成功后客户端和服务端会建立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];
    // 发邮箱声频

请注意不同音频格式一帧大小的字节数不同，大发pk10建议：

1. 未压缩的PCM格式，每次发送音频间隔40ms，每次发送音频字节数1280B；
   
2. 讯飞定制speex格式，每次发送音频间隔40ms，假如16k的压缩等级为7，则每次发送61B的整数倍；
   
3. 标准开源speex格式，每次发送音频间隔40ms，假如16k的压缩等级为7，则每次发送60B的整数倍；
   

speex相关说明详见speex编码 (opens new window)

整个会话时长最多持续60s，或者超过10s未发送数据，服务端会主动断开连接。
数据上传完毕，客户端需要上传一次数据结束标识表示会话已结束，详见下方data参数说明。

# 请求参数

# 公共参数说明

# 业务参数

注： 多候选效果是由引擎决定的，并非绝对的。即使设置了多候选，如果引擎并没有识别出候选的词或句，返回结果也还是单个。
注： 以上common和business参数只需要在握手成功后的第一帧请求时带上。
注：
坐席助手：电话坐席助手，一般用于人与人对话的场景。
语音导航：电话语音导航，一般用于机器与人对话的场景。
语音分析：基于大量存量的电话客服录音做质检，即事后音频转文字的场景(识别率会优于前两者)。

# 业务数据流参数

    {  
        "common":{
           // 公共信息表单提交参数设置
           "app_id":"123456"  
        },
        "business":{
            "language":"zh_cn",
            "domain":"iat",
            "accent":"mandarin"
        },
        "data":{
                "status":0,
                "format":"audio/L16;rate=16000",
                "encoding":"raw",
                "audio":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."    
        }
    }

    {
    "data":{
      "status":2
        }
    }

# 返回参数

# 动态修正返回参数

若开通了动态修正功能并设置了dwa=wpgs（仅中文支持），还有如下字段返回：
注：动态修正结果解析可参考页面下方的java demo。

# vinfo返回参数

返回参数示例（动态修正dwa=wpgs）
注：动态修正结果解析可参考页面下方的java demo。

	{
	  "code": 0,
	  "message": "success",
	  "sid": "iatxxxxxxxxxxxxx",
	  "data": {
	    "result": {
	      "bg": 0,
	      "ed": 0,
	      "ls": false,
	      "pgs": "rpl",
	      "rg": [
	        1,
	        1
	      ],
	      "sn": 2,
	      "ws": [
	        {
	          "bg": 0,
	          "cw": [
	            {
	              "sc": 0,
	              "w": "测试仪"
	            }
	          ]
	        },
	        {
	          "bg": 0,
	          "cw": [
	            {
	              "sc": 0,
	              "w": "一会"
	            }
	          ]
	        }
	      ]
	    },
	    "status": 1
	  }
	}

{
  "code": 0,
  "message": "success",
  "sid": "iatxxxxxxxxxxxxxx",
  "data": {
    "result": {
      "bg": 0,
      "ed": 0,
      "ls": false,
      "sn": 1,
      "vad": {
        "ws": [
          {
            "bg": 40,
            "ed": 366,
            "eg": 63.58
          }
        ]
      },
      "ws": [
        {
          "bg": 53,
          "cw": [
            {
              "sc": 0,
              "w": "4月"
            }
          ]
        },
        {...},
        {
          "bg": 293,
          "cw": [
            {
              "sc": 0,
              "w": "参赛者"
            }
          ]
        }
      ]
    },
    "status": 1
  }
}

{
  "code": 0,
  "message": "success",
  "sid": "iatxxxxxxxxxxxxx",
  "data": {
    "result": {
      "bg": 0,
      "ed": 0,
      "ls": false,
      "sn": 1,
      "ws": [
        {
          "bg": 35,
          "cw": [
            {
              "sc": 0,
              "w": "打电销给梁玉生"
            },
            {
              "sc": 0,
              "w": "打点话给梁玉升"
            }
          ]
        }
      ]
    },
    "status": 0
  }
}

{
  "code": 0,
  "message": "success",
  "sid": "iatxxxxxxxxxxxxxx",
  "data": {
    "result": {
      "bg": 0,
      "ed": 0,
      "ls": false,
      "sn": 1,
      "ws": [
        {...},
        {
          "bg": 159,
          "cw": [
            {
              "sc": 0,
              "w": "梁"
            }
          ]
        },
        {
          "bg": 191,
          "cw": [
            {
              "sc": 0,
              "w": "玉"
            },
            {
              "sc": 0,
              "w": "育"
            }
          ]
        },
        {
          "bg": 215,
          "cw": [
            {
              "sc": 0,
              "w": "生"
            },
            {
              "sc": 0,
              "w": "升"
            }
          ]
        }
      ]
    },
    "status": 0
  }
}

# 错误码

备注：如出现下述列表中没有的错误码，可到 这里 (opens new window) 查询。

# 调用示例

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

注： 其他开发语言请参照 接口调用流程 进行开发，也欢迎热心的开发者到 分享你们的demo。

# 音频样例

注： 音频文件的录制和格式确认（推荐使用Cool Edit Pro工具），以及讯飞定制SPEEX编码工具请参考这里： 音频格式说明 (opens new window)

# 视频教程

# 常见问题

# 语音听写的APIKey在哪里查询到？

答：操纵台--我的采用---寻找相应的采用的话音听写（普鲁士蓝染色）服务---即能检查到。

# webapi流式听写能获取到语音听写结果为空或错误内容或者不全，原因是什么？

答：原因可能如下；
1、音频格式不正确，请使用Cool Edit Pro工具（网页搜索下载即可）查看音频格式，webapi听写流式版：支持的格式是pcm、speex、speex-wb，其中中文普通话和英文还支持mp3格式
音频采样率要是 16k 或者 8k、采样精度16 位、单声道音频。样例音频请参照音频样例
2、音频中间有静音或者杂音音频超过了后端点（不设置默认为2000ms）的设置，此时请使用Cool Edit Pro工具查看音频内容，并且设置后端点（vad_eos）为最大值10000ms
包含超过后端点最大值的静音或者杂音时，音频识别不完整是正常的

# 语音听写WebAPI支持的音频格式有哪些？

答：大力能够8k和16k取样率、16bit、单声道的pcm、mp3、speex图片模式的双声道文件。需主意mp3图片模式的双声道文件仅大力能够常常各种类型话和英文字母。

# 语音听写最长支持多少秒之内的音频？

答：听写帮助区分60s之间的双声道。

# 语音听写Webapi支持多少路并发？如何提高并发？

答：初始大力支持50路消息队列，如需较多消息队列可还需准备订单实现资讯。

# 听写报错10163，length of $.data.audio must be between 0,13000是什么原因？

答：听写frameSize传的双声道程度base64商品代码后没法稍微超出13000B，默认要求传1280B不可以传值过大。

# 为什么每隔一段时间不发送数据就会断开连接？

答：听写vad_eos为支持系统的最久隔音事件，大于这类事件会以为语音完会自动断电接触。

# 最多支持多少热词，是否可以扩容？

答：操控台多兼容2000个适用级热搜词，暂不兼容扩盘。

# 如何限制IP？

答：可顺利通过在IP白名册配置我服务于的IP具体ip地址，规定另外的IP具体ip地址访问浏览。