讯飞听见语音识别接口调用流程和参数配置详解

必须调用讯飞听见API而非网页上传；需实名认证获取AppID、API Key、API Secret；音频须为16/8kHz单声道PCM-WAV；短音频用RESTful同步调用，长音频推荐WebSocket流式上传。

要让程序自动把语音转成文字，必须调用讯飞听见的语音识别接口，而不是网页上传——因为网页操作无法嵌入到你的系统里，也不支持批量、定时、API级集成。

获取合法调用凭证

访问讯飞开放平台官网（https://www.xfyun.cn），用手机号完成实名认证。进入控制台 → 新建应用 → 服务类型选“语音听写”或“实时语音转写”。创建后立即获得三项密钥：【AppID、API Key、API Secret】。这三者缺一不可，且每个应用独立生成，不能混用。

注意：免费额度每月5小时，新用户首次创建应用时可额外领取一个500分钟体验包，需手动点击“领取”按钮激活。

音频文件预处理硬性要求

讯飞接口对输入音频有明确限制，不满足将直接返回错误码10203（格式不支持）或10403（采样率不符）：

必须为单声道WAV文件；采样率严格限定为16kHz或8kHz；位深为16bit；编码格式为PCM（即L16）。

若原始音频是MP3、M4A或立体声WAV，须用ffmpeg转码：ffmpeg -i input.mp3 -ar 16000 -ac 1 -f wav -c:a pcm_s16le output.wav。跳过此步会导致识别结果为空或乱码。

文件大小不能超过64MB。超限音频需分片，但每片仍须满足上述格式与参数。

RESTful API调用三步执行链

方法一：同步一次性提交（适合≤60秒短音频）

第一步：Base64编码音频二进制数据，确保编码后字符串无换行符；

第二步：构造param参数JSON并Base64编码，内容必须包含{"engine_type":"iat","aue":"raw","audio_format":"wav","sample_rate":16000,"scene":"main"}；

第三步：按规则拼接签名字符串APIKeynX-Param(Base64值)nX-CurTime(当前时间戳)，用HMAC-SHA256 + API Secret计算摘要，再Base64编码得到X-CheckSum；

第四步：发起POST请求到https://api.xfyun.cn/v1/service/v1/iat，Header中填入X-Appid、X-CurTime、X-Param、X-CheckSum和Content-Type: application/json，Body为{"data":""}。

方法二：WebSocket流式上传（推荐用于长音频或需实时反馈场景）

① 使用API Key和API Secret生成带签名的鉴权URL，时间戳必须为UTC时间（非本地时间），误差超过15分钟即拒绝连接；

② 建立WebSocket连接后，首帧必须发送启动参数JSON，含{"common":{"app_id":"xxx"},"business":{"language":"zh_cn","domain":"iat","accent":"mandarin","dwa":"wpgs","pdt":"audio","tte":"utf8"}}；

③ 音频数据按1280字节/帧切分，每帧封装为JSON对象：{"status":0/1/2,"format":"audio/L16;rate=16000","encoding":"raw","audio":""}，status=0为首帧，=1为中间帧，=2为末帧——【末帧未发送将导致识别中断且无返回】；

④ 服务器返回结果中，data.status=2表示最终结果，data.result.ws数组内每个ws元素含word（识别词）、phone（音素）、bg/ed（起止时间帧），需自行拼接text字段。

关键参数配置说明

language字段决定底层模型，中文普通话填zh_cn，粤语填yue，英语填en_us。填错会导致整段识别失败，而非仅准确率下降。

开启智能格式化（dwa=wpgs）可自动加标点、数字规整（如“一二三”→“123”），但会略微增加响应延迟；关闭则返回纯文本流。

accent参数影响方言适配，普通话必须填mandarin；四川话填sichuanhua；东北话填dongbeihua。该字段与language联动，单独修改无效。

热词增强需在请求体business对象中加入"customization":{"hotword":"关键词1,关键词2"}，热词最多200个，总字符≤1000，仅支持UTF-8中文，英文热词无效。