Transcribe Short Audio via Azure REST API

This skill transcribes short audio files (up to 60 seconds) using Azure's Speech-to-Text REST API for short audio, deliberately avoiding any SDK dependency - just requests and HTTP calls. After creating a Speech resource in the Azure Portal and reading its key and region into AZURE_SPEECH_KEY/AZURE_SPEECH_REGION (or using the region-derived endpoint directly), a POST to https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1 with the audio file as the request body and query parameters for language (required) and format returns a transcription. Audio requirements favor WAV/PCM at 16kHz mono (recommended) or OGG/OPUS (smaller file size), each requiring an exact Content-Type header; limitations are explicit - 60 seconds max audio (30 seconds for pronunciation assessment), and no partial/interim results, only a final transcript. Two response formats are covered: simple (default, just RecognitionStatus, DisplayText, offset, and duration) and detailed (adding an NBest array with confidence scores and Display/ITN/Lexical/MaskedITN text variants per candidate). For lower latency, audio can be streamed in chunks via Transfer-Encoding: chunked and a generator yielding fixed-size chunks rather than reading the whole file into memory first. Authentication supports either the subscription key directly in the Ocp-Apim-Subscription-Key header, or exchanging that key for a bearer token (valid 10 minutes, recommended to cache for ~9) via a separate issueToken endpoint. Query parameters also cover profanity handling (masked, removed, or raw) and the recognition status values that can come back (Success, NoMatch, InitialSilenceTimeout, BabbleTimeout, Error) - production code is expected to handle all of them, not just success. Error handling distinguishes HTTP 400 (bad language code or audio format), 401 (bad key/token), and 403 (missing authorization header) with specific guidance per code. An async variant using aiohttp mirrors the sync requests-based flow. A language-code reference table covers ten common locales (en-US, en-GB, de-DE, fr-FR, es-ES, es-MX, zh-CN, ja-JP, ko-KR, pt-BR) with a pointer to the full supported-language list. The skill is explicit about when NOT to use this API: audio longer than 60 seconds, real-time streaming transcription, partial/interim results, speech translation, custom speech models, or batch transcription of many files all require the full Speech SDK or the Batch Transcription API instead.

Use this skill for simple, short (≤60 second) speech-to-text transcription without adding an SDK dependency - voice commands, short voice notes, or quick prototyping. Do not use it for audio over 60 seconds, real-time/streaming transcription, partial results, speech translation, custom speech models, or batch transcription of many files - all of those require the Speech SDK or Batch Transcription API instead, which this skill explicitly defers to. The endpoint can also be set directly via AZURE_SPEECH_ENDPOINT instead of deriving it from the region.

Input is a short audio file (WAV/PCM 16kHz mono recommended, or OGG/OPUS) plus a language code and optional format/profanity settings. Output is a JSON transcription result - either simple (display text) or detailed (confidence-scored N-best candidates) - with an explicit recognition status.

Built directly on Azure AI Speech's REST API (no SDK), authenticated via a subscription key header or a short-lived bearer token from the Speech token-issuance endpoint, using Python's requests (or aiohttp for async).

pip install requests

Python developers who need simple, short-audio speech-to-text transcription without adding the full Azure Speech SDK as a dependency, and who don't need streaming, translation, or custom models.