音频开发 / 系统课时

调用首个语音识别接口

调用首个语音识别接口

文件式 ASR 的最小链路是:准备符合要求的音频,携带认证信息发起请求,再从响应中读取文本、语言和时间信息。本节使用一个统一 HTTP 接口契约完成第一次调用,并把认证失败、请求参数错误和音频格式错误分别处理清楚。

学习目标

  • 能组织一次包含音频文件与识别参数的 ASR 请求
  • 能读取识别文本、语言和分段时间信息
  • 能根据状态码定位认证、参数和媒体格式问题

约定最小接口契约

不同 ASR 厂商的 URL、参数和返回字段并不完全相同,因此业务代码不应默认所有供应商都使用同一种格式。本节为了集中练习请求链路,约定一个统一接口:客户端向 POST /v1/asr/transcriptions 上传 multipart 表单。

表单中的 file 保存音频文件,language 指定语言,timestamps 控制是否返回分段时间。认证使用 Authorization: Bearer <TOKEN>。成功响应包含完整文本 text、语言 language 和时间分段 segments。接入真实服务时,应把这些名称映射到供应商实际接口定义。

文件式 ASR 请求与异常分支

发起第一次请求

运行前准备 sample.wav,把 ASR_BASE_URL 和 ASR_TOKEN 环境变量设置为实际服务地址与令牌,并确保 Python 环境已经安装 requests。下面代码包含文件上传、认证、参数发送、状态码检查和结果读取,可以直接作为最小客户端入口。

python
import os
import requests

base_url = os.environ["ASR_BASE_URL"].rstrip("/")
token = os.environ["ASR_TOKEN"]

with open("sample.wav", "rb") as audio_file:
    response = requests.post(
        f"{base_url}/v1/asr/transcriptions",
        headers={"Authorization": f"Bearer {token}"},
        files={"file": ("sample.wav", audio_file, "audio/wav")},
        data={"language": "zh", "timestamps": "segment"},
        timeout=60,
    )

if response.status_code == 401:
    raise RuntimeError("认证失败:检查 ASR_TOKEN")
if response.status_code == 415:
    raise RuntimeError("音频格式不受支持:检查 Content-Type 与实际编码")
if response.status_code >= 400:
    raise RuntimeError(f"请求失败:HTTP {response.status_code} {response.text}")

result = response.json()
print("text:", result["text"])
print("language:", result["language"])

for segment in result.get("segments", []):
    print(f'{segment["start"]:.2f}-{segment["end"]:.2f}: {segment["text"]}')

预期结果:成功请求的 HTTP 状态码为 200。假设 sample.wav 中说的是“你好,欢迎使用语音识别。”,服务按本课约定返回文本、语言和一个时间分段,响应体形态如下;分段时间会根据实际识别结果变化。

json
{"text":"你好,欢迎使用语音识别。","language":"zh","segments":[{"start":0.0,"end":2.84,"text":"你好,欢迎使用语音识别。"}]}

对应的控制台输出形态为:

text
text: 你好,欢迎使用语音识别。
language: zh
<TIME>-<TIME>: 你好,欢迎使用语音识别。

<TIME> 表示实际的分段起止秒数。真实接口如果不提供时间信息,可以让 segments 为空;如果业务必须生成字幕或做音频高亮,则应明确选择支持时间戳的响应模式。

按状态码定位基本异常

401 Unauthorized 通常表示令牌缺失、失效,或者认证头格式不符合接口要求。这种错误属于确定性错误,在修改认证信息之前反复重试没有意义。

400 Bad Request 一般说明请求已经到达服务端,但参数无法通过校验,例如字段名错误、语言值不合法或 multipart 表单缺少文件。排查时应保留服务返回的错误体,并与实际接口文档逐项对照。

415 Unsupported Media Type 更直接地指向音频类型问题。即使上传文件叫 sample.wav,内部编码仍可能不满足接口要求,因此要同时检查真实编码、采样率、声道数以及请求中的 Content-Type。

不要把 HTTP 200 当成识别完成

请求成功后还需要检查响应内容。最基本的条件是 text 存在且不是空字符串;业务依赖语言信息时还要验证 language;业务依赖字幕或时间轴时,则需要检查每个分段的 start 不大于 end,并确认分段整体按时间递增。

生产环境还应记录请求 ID、耗时、HTTP 状态码和错误分类,方便定位模型慢、网络慢还是参数错误。但日志中不要保存完整认证令牌,也不要默认记录包含敏感信息的原始音频。

完成这些检查后,文件式语音识别的最小链路就闭环了:音频作为请求输入,接口完成认证与格式校验,模型产生识别结果,客户端再验证文本和时间信息。后续扩展流式识别时,变化主要发生在音频传输和增量结果处理方式,而这套输入契约与错误分类仍然适用。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

调用首个语音识别接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通