思必驰API接入实操：语音识别接口调用与密钥配置
思必驰语音识别 API 主要通过 WebSocket 协议流式传输音频，调用前需要先在开放平台创建应用，拿到 AppKey 和 AppSecret，再用 HMAC-SHA1 对请求参数签名生成带鉴权的连接地址。
下面按实际接入顺序说明每一步的操作和验证方式。
创建应用并确认接口类型
登录思必驰开放平台控制台，进入应用管理页面创建新应用。
创建时注意选择「语音识别」能力，部分能力需要单独申请开通。
应用创建完成后，在应用详情页可以看到：
AppKey：应用唯一标识，用于拼接鉴权参数AppSecret：签名密钥，不要写入前端代码或公开仓库- 接口地址：语音识别 WebSocket 地址，以控制台当前展示为准
如果控制台显示能力「未开通」，需要先提交开通申请，审核通过后再进行后续调用。
不同能力对应的接口路径和参数可能不同，以控制台文档为准。
生成鉴权连接地址
思必驰 WebSocket 接口通常要求把签名信息放在 URL 查询参数中。
签名逻辑是：将 AppKey、时间戳等参数按规则拼接，用 AppSecret 做 HMAC-SHA1 计算，再对结果做 Base64 编码。
以下为 Python 示例，签名参数名请以你控制台文档为准：
import hmac, hashlib, base64, time, urllib.parse
app_key = "你的AppKey"
app_secret = "你的AppSecret"
timestamp = str(int(time.time()))
# 拼接待签名字符串，具体顺序参考官方文档
sign_str = f"app_key={app_key}×tamp={timestamp}"
sign = hmac.new(app_secret.encode(), sign_str.encode(), hashlib.sha1).digest()
sign_b64 = base64.b64encode(sign).decode()
query = urllib.parse.urlencode({
"app_key": app_key,
"timestamp": timestamp,
"sign": sign_b64
})
url = f"wss://api.example.com/asr?{query}"
print(url)把打印出的 URL 用 websocat 或 Python websockets 库试连一次，能建立连接并收到服务端握手消息，说明签名有效。
如果返回 401 或连接立即关闭，优先检查时间戳是否与服务器偏差过大、签名拼接顺序是否与文档一致。
发送音频与接收识别结果
连接建立后，按接口约定发送音频数据。
思必驰流式识别通常要求：
- 音频格式：PCM 或控制台指定的编码格式，采样率、位深、声道数需与请求参数匹配
- 分片发送：每包大小参考文档建议值，不要一次性发送超大文件
- 结束标记：音频发送完后发送结束帧，等待服务端返回最终结果
调用时建议先设置超时和重试上限，避免网络抖动导致程序长时间挂起。
接收到的识别结果一般是 JSON 格式，需要按字段提取文本内容。
常见报错排查
401 鉴权失败：检查 AppSecret 是否复制完整、时间戳是否为秒级、签名参数名是否与文档一致。
连接超时：确认服务器出网方向 443 端口未被安全组或防火墙拦截，可以用 curl -v https://开放平台域名 测试连通性。
识别结果为空：检查音频采样率是否与请求参数一致，以及是否发送了结束帧。
上线前的验证清单
- 用控制台示例音频跑通一次完整识别流程
- 在服务器上单独测试出网连接，排除本地环境干扰
- 将 AppSecret 放入环境变量或配置中心，不提交到代码仓库
- 记录一次正常调用的请求参数和返回结构，便于后续比对
思必驰 API 的接入门槛主要在签名生成和音频参数匹配上，先把这两步单独验证通过，再接入业务代码，排错会快很多。
