Azure Speech-to-Text REST API: Simple Transcription for Short Audio

When you need quick speech recognition for short audio clips without the complexity of a full SDK, Azure's Speech-to-Text REST API offers a lightweight, straightforward solution. This skill enables AI agents to transcribe audio files up to 60 seconds using simple HTTP requests.

What This Skill Does

The azure-speech-to-text-rest-py skill provides a minimalist approach to speech recognition. Instead of installing and configuring the Azure Speech SDK, you can transcribe audio files with standard HTTP POST requests. This makes it perfect for quick integrations, serverless functions, and scenarios where you need simple transcription without real-time streaming or advanced features.

The skill handles audio in WAV or OGG format, supports over 100 languages, and returns either simple text results or detailed responses with confidence scores and alternative transcriptions. It's designed for short-form audio like voice commands, brief recordings, or user messages—anything under 60 seconds.

Getting Started

First, you'll need an Azure Speech resource. Create one in the Azure Portal (there's a free tier available), then grab your API key and region from the Keys and Endpoint section. Set these as environment variables:

export AZURE_SPEECH_KEY="your-api-key"
export AZURE_SPEECH_REGION="eastus"  # or your region

Install the only dependency you'll need:

pip install requests

Here's the simplest possible implementation:

import os
import requests

def transcribe_audio(audio_file_path: str, language: str = "en-US") -> str:
    region = os.environ["AZURE_SPEECH_REGION"]
    api_key = os.environ["AZURE_SPEECH_KEY"]
    
    url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"
    
    headers = {
        "Ocp-Apim-Subscription-Key": api_key,
        "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000",
        "Accept": "application/json"
    }
    
    params = {"language": language}
    
    with open(audio_file_path, "rb") as audio_file:
        response = requests.post(url, headers=headers, params=params, data=audio_file)
    
    response.raise_for_status()
    return response.json()["DisplayText"]

# Usage
text = transcribe_audio("recording.wav", "en-US")
print(text)  # "Remind me to buy groceries."

That's it. No SDK initialization, no complex configuration—just a POST request with your audio file.

Key Features

Audio Format Flexibility: The API accepts WAV (PCM 16kHz) and OGG (OPUS) formats. WAV is recommended for compatibility, but OGG offers smaller file sizes if bandwidth matters.

Response Format Options: Choose between simple format (just the transcribed text) or detailed format (with confidence scores, multiple hypotheses, and normalized text variations). Detailed format is valuable when you need to assess transcription quality or offer alternatives.

Chunked Transfer Encoding: Stream audio in chunks rather than uploading the entire file first. This reduces latency and improves responsiveness, especially for longer clips approaching the 60-second limit.

Authentication Flexibility: Use either subscription keys (simple) or bearer tokens (more secure, can be rotated). Bearer tokens are valid for 10 minutes and are ideal for distributed systems.

Profanity Handling: Configure how the API handles profanity—mask it with asterisks, remove it entirely, or include it raw. This is crucial for user-facing applications.

Language Support: Over 100 languages and dialects supported, from English variants to Mandarin, Arabic, and less common languages. Just specify the correct language code.

Usage Examples

Get Detailed Results with Confidence Scores:

def transcribe_detailed(audio_path: str, language: str = "en-US") -> dict:
    region = os.environ["AZURE_SPEECH_REGION"]
    api_key = os.environ["AZURE_SPEECH_KEY"]
    
    url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"
    
    headers = {
        "Ocp-Apim-Subscription-Key": api_key,
        "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000"
    }
    
    params = {"language": language, "format": "detailed"}
    
    with open(audio_path, "rb") as f:
        response = requests.post(url, headers=headers, params=params, data=f)
    
    result = response.json()
    best = result["NBest"][0]
    
    return {
        "text": best["Display"],
        "confidence": best["Confidence"],
        "alternatives": [alt["Display"] for alt in result["NBest"][1:]]
    }

Use Chunked Transfer for Lower Latency:

def transcribe_chunked(audio_path: str, language: str = "en-US") -> str:
    region = os.environ["AZURE_SPEECH_REGION"]
    api_key = os.environ["AZURE_SPEECH_KEY"]
    
    url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"
    
    headers = {
        "Ocp-Apim-Subscription-Key": api_key,
        "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000",
        "Transfer-Encoding": "chunked",
        "Expect": "100-continue"
    }
    
    params = {"language": language}
    
    def generate_chunks(file_path: str):
        with open(file_path, "rb") as f:
            while chunk := f.read(1024):
                yield chunk
    
    response = requests.post(url, headers=headers, params=params, data=generate_chunks(audio_path))
    return response.json()["DisplayText"]

Async Version for Concurrent Processing:

import aiohttp
import asyncio

async def transcribe_async(audio_path: str, language: str = "en-US") -> str:
    region = os.environ["AZURE_SPEECH_REGION"]
    api_key = os.environ["AZURE_SPEECH_KEY"]
    
    url = f"https://{region}.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1"
    
    headers = {
        "Ocp-Apim-Subscription-Key": api_key,
        "Content-Type": "audio/wav; codecs=audio/pcm; samplerate=16000"
    }
    
    params = {"language": language}
    
    async with aiohttp.ClientSession() as session:
        with open(audio_path, "rb") as f:
            audio_data = f.read()
        async with session.post(url, headers=headers, params=params, data=audio_data) as response:
            result = await response.json()
            return result["DisplayText"]

# Process multiple files concurrently
texts = await asyncio.gather(
    transcribe_async("audio1.wav"),
    transcribe_async("audio2.wav"),
    transcribe_async("audio3.wav")
)

Best Practices

Choose the Right Audio Format: Use WAV PCM at 16kHz mono for maximum compatibility. If you're receiving audio in other formats, convert it first. The API is strict about format requirements.

Handle All Recognition Status Values: Don't assume success. Check the RecognitionStatus field—it could be NoMatch (speech detected but not recognized), InitialSilenceTimeout (only silence), or BabbleTimeout (only noise). Handle each case appropriately.

Cache Bearer Tokens: If using token authentication, cache tokens for 9 minutes (they're valid for 10). Don't request a new token for every transcription—that's wasteful and slower.

Specify the Correct Language: The API doesn't auto-detect language. If you specify the wrong language code, recognition quality will be poor. When supporting multiple languages, detect the language first or let users specify it.

Use Detailed Format When Quality Matters: The confidence score tells you how certain the API is about its transcription. For critical applications, reject low-confidence results and ask users to re-record.

Implement Proper Error Handling: Network issues, invalid audio formats, expired tokens—many things can go wrong. Catch exceptions, check HTTP status codes, and provide meaningful error messages.

When to Use This Skill

Perfect for:

• Voice commands and short user messages


• Transcribing audio clips in serverless functions


• Quick integrations where SDK overhead isn't justified


• Prototyping speech features before committing to the full SDK


• Scenarios where you already have complete audio files


• Applications with simple transcription needs

NOT suitable for:

• Audio longer than 60 seconds (use Batch Transcription API)


• Real-time streaming transcription (use Speech SDK with WebSocket)


• Applications needing partial/interim results during transcription


• Speech translation (requires SDK)


• Custom speech models or domain-specific vocabulary (requires SDK)


• Pronunciation assessment for language learning (use SDK)

The REST API is wonderfully simple, but it's deliberately limited. For production applications with complex requirements, graduate to the Speech SDK.

Related Skills

Explore the full Azure Speech-to-Text REST API skill: /ai-assistant/azure-speech-to-text-rest-py

Source

This skill is provided by Microsoft as part of Azure AI Services.

---

Ready to transcribe short audio with minimal code? The REST API is your simplest path to speech recognition.