Transcribe Short Audio via Azure REST API

This skill teaches an agent to transcribe short audio files, up to 60 seconds, using Azure's Speech-to-Text REST API directly over HTTP, with no Speech SDK dependency - just the requests library. It covers building the recognition request against https://<region>.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1 with the right Content-Type for WAV PCM 16kHz mono (recommended) or OGG OPUS audio, choosing simple or detailed response format, reading RecognitionStatus and DisplayText (or, in detailed format, the NBest array with confidence scores), chunked transfer for lower latency, subscription-key versus bearer-token authentication, profanity handling, and both a synchronous (requests) and async (aiohttp) implementation.

Use it for short, single-shot transcription jobs where a plain REST call is simpler than pulling in the full Speech SDK - voice commands, short recordings, quick prototypes. Switch to the Speech SDK or the Batch Transcription API instead when audio runs longer than 60 seconds, when real-time streaming or partial/interim results are needed, for speech translation, custom speech models, or batch transcription of many files - this REST endpoint returns only a final result and has no streaming mode. Its stated best practices: use WAV PCM 16kHz mono for best compatibility, enable chunked transfer for lower latency, cache bearer tokens for about 9 minutes since they are valid for 10, specify the correct language for accurate recognition, use detailed format when confidence scores are needed, and handle every RecognitionStatus value in production code.

Inputs: AZURE_SPEECH_KEY and AZURE_SPEECH_REGION (or AZURE_SPEECH_ENDPOINT directly) as environment variables, an audio file (WAV/PCM/16kHz/mono recommended, or OGG/OPUS for smaller size), and query parameters language (required, e.g. en-US), format (simple or detailed, default simple), and profanity (masked, removed, or raw, default masked). Outputs: a JSON body with RecognitionStatus (Success, NoMatch, InitialSilenceTimeout, BabbleTimeout, or Error), DisplayText in simple format, or an NBest array of candidates with Confidence, Display, ITN, Lexical, and MaskedITN fields in detailed format, plus HTTP status codes to branch on - 400 for a bad request, 401 for an invalid key or token, 403 for a missing authorization header.

Azure AI Speech (speech-to-text recognition endpoint, subscription-key or bearer-token auth via the /sts/v1.0/issueToken token endpoint), consumed through the requests library synchronously or aiohttp asynchronously. A bundled reference file, references/pronunciation-assessment.md, covers pronunciation assessment parameters and scoring, which caps at 30 seconds of audio rather than 60.

pip install requests

Python developers who need quick, short-audio speech-to-text without adding the Speech SDK as a dependency - voice commands, short clips, or lightweight prototypes.