azure-speech-to-text-rest-py

用途

本技能用于通过 REST API 对短音频文件（最长 60 秒）进行语音转文本识别，使用 Python 的 HTTP 请求实现，无需依赖 Azure Speech SDK。适合需要简单、轻量级语音识别集成的场景。

主要能力

• 对不超过 60 秒的音频文件进行语音识别，返回文本结果。
• 支持简单（simple）与详细（detailed）两种响应格式；详细格式包含置信度、ITN、Lexical、MaskedITN 等字段。
• 支持分块传输（chunked transfer），可降低延迟。
• 支持订阅密钥（Ocp-Apim-Subscription-Key）与 Bearer Token 两种认证方式；Token 有效期为 10 分钟。
• 支持查询参数：language（必填）、format（simple/detailed）、profanity（masked/removed/raw）。
• 提供识别状态值说明：Success、NoMatch、InitialSilenceTimeout、BabbleTimeout、Error。
• 提供错误处理示例（400、401、403 等状态码）与异步版本（aiohttp）示例。
• 附带参考文件 references/pronunciation-assessment.md，包含发音评估参数与评分说明。

使用方式

1. 前置条件：创建 Azure 订阅与语音资源，在 Azure 门户获取密钥与终结点。
2. 设置环境变量：AZURE_SPEECH_KEY、AZURE_SPEECH_REGION（如 eastus、westus2、westeurope），或直接使用 AZURE_SPEECH_ENDPOINT。
3. 安装依赖：pip install requests（异步版本需 aiohttp）。
4. 调用 REST 终结点：https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1，通过 POST 发送音频数据，并在请求头中设置 Content-Type 与认证信息。
5. 音频要求：推荐 WAV PCM 16kHz 单声道；也支持 OGG OPUS 16kHz 单声道。Content-Type 需对应设置，例如 audio/wav; codecs=audio/pcm; samplerate=16000 或 audio/ogg; codecs=opus。
6. 解析响应：根据 RecognitionStatus 判断识别是否成功，并从 DisplayText 或 NBest 中获取文本。

适用场景

• 对短音频文件进行快速语音转文本。
• 不希望引入 Speech SDK、仅使用 HTTP 请求的轻量集成。
• 需要置信度等详细识别信息的场景。
• 需要低延迟流式发送音频块的场景。

限制

• 音频最长 60 秒；发音评估最长 30 秒。
• 不提供部分/中间结果，仅返回最终结果。
• 不适用于以下需求：超过 60 秒的音频、实时流式转写、部分/中间结果、语音翻译、自定义语音模型、批量转写多个文件；这些场景应改用 Speech SDK 或 Batch Transcription API。
• 使用前需具备 Azure 订阅与语音资源；具体收费与价格信息暂未提供。
• 输出结果不应替代针对具体环境的验证、测试或专家审查；若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。