Meta

• Author:
• Tags azure , azure sdk
• Requires: Python >=3.9

Classifiers

• Development Status
  • 5 - Production/Stable
• Programming Language
  • Python
  • Python :: 3
  • Python :: 3 :: Only
  • Python :: 3.9
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13

Azure AI Speech Transcription client library for Python

Azure AI Speech Transcription is a service that provides advanced speech-to-text capabilities, allowing you to transcribe audio content into text with high accuracy. This client library enables developers to integrate speech transcription features into their Python applications.

Use the client library to:

• Transcribe audio files and audio URLs to text
• Support multiple languages with automatic language detection
• Customize transcription with domain-specific models
• Enable speaker diarization to identify different speakers
• Configure profanity filtering and channel separation

Source code | Package (PyPI) | API reference documentation | Product documentation

Getting started

Prerequisites

• Python 3.9 or later is required to use this package.
• You must have an Azure subscription to use this package.
• An Azure AI Speech resource in your Azure account.

Install the package

Install the Azure AI Speech Transcription client library for Python with pip:

pipinstallazure-ai-transcription

Create an Azure AI Speech resource

You can create an Azure AI Speech resource using the Azure Portal or Azure CLI.

Here's an example using the Azure CLI:

azcognitiveservicesaccountcreate\
--name<your-resource-name>\
--resource-group<your-resource-group>\
--kindSpeechServices\
--skuF0\
--location<region>

Authenticate the client

In order to interact with the Azure AI Speech Transcription service, you'll need to create an instance of the TranscriptionClient class. The client supports two authentication methods:

1. Azure Active Directory (Azure AD) Authentication - Using DefaultAzureCredential or other token credentials from azure-identity
2. API Key Authentication - Using AzureKeyCredential with your Speech resource's API key

Get credentials

You can get the endpoint and API key from the Azure Portal or by running the following Azure CLI command:

azcognitiveservicesaccountkeyslist\
--name<your-resource-name>\
--resource-group<your-resource-group>

The endpoint can be found in the "Keys and Endpoint" section of your Speech resource in the Azure Portal.

Create the client with API Key

Using an API key is the simplest authentication method:

importos
fromazure.core.credentialsimport AzureKeyCredential
fromazure.ai.transcriptionimport TranscriptionClient

endpoint = os.environ.get("SPEECH_ENDPOINT")
api_key = os.environ.get("SPEECH_API_KEY")

credential = AzureKeyCredential(api_key)
client = TranscriptionClient(endpoint=endpoint, credential=credential)

Create the client with Azure AD (Recommended for Production)

Azure AD authentication provides better security and is recommended for production scenarios. First, install the azure-identity package:

pipinstallazure-identity

Then create the client using DefaultAzureCredential:

importos
fromazure.identityimport DefaultAzureCredential
fromazure.ai.transcriptionimport TranscriptionClient

endpoint = os.environ.get("SPEECH_ENDPOINT")

# DefaultAzureCredential will try multiple authentication methods
# including environment variables, managed identity, Azure CLI, etc.
credential = DefaultAzureCredential()
client = TranscriptionClient(endpoint=endpoint, credential=credential)

Note: When using Azure AD authentication, ensure your Azure identity has the appropriate role assigned (e.g., Cognitive Services User or Cognitive Services Speech User) on the Speech resource.

Key concepts

TranscriptionClient

The TranscriptionClient is the primary interface for developers using the Azure AI Speech Transcription client library. It provides the transcribe method to convert audio into text.

Transcription Options

The service supports various transcription options including:

• Language Detection: Automatic detection from supported locales or specify candidate locales
• Custom Models: Map locales to custom model URIs for domain-specific vocabulary
• Diarization: Identify and separate different speakers in the audio
• Channel Separation: Process up to two audio channels separately
• Profanity Filtering: Control how profanity appears in transcripts (None, Removed, Tags, Masked)
• Enhanced Mode: Additional processing capabilities
• Phrase Lists: Improve accuracy for specific terms and phrases

Transcription Results

Results include:

• Full transcript text per channel
• Segmented phrases with timestamps
• Word-level details including confidence scores
• Duration information

Examples

The following sections provide several code snippets covering common scenarios:

• Transcribe an audio file
• Transcribe from a URL
• Transcribe with enhanced mode
• Using async client

For more extensive examples including speaker diarization, multi-language detection, profanity filtering, and custom phrase lists, see the samples directory.

Transcribe an audio file

fromazure.core.credentialsimport AzureKeyCredential
fromazure.ai.transcriptionimport TranscriptionClient
fromazure.ai.transcription.modelsimport TranscriptionContent, TranscriptionOptions

# Get configuration from environment variables
endpoint = os.environ["AZURE_SPEECH_ENDPOINT"]

# We recommend using role-based access control (RBAC) for production scenarios
api_key = os.environ.get("AZURE_SPEECH_API_KEY")
if api_key:
 credential = AzureKeyCredential(api_key)
else:
 fromazure.identityimport DefaultAzureCredential

 credential = DefaultAzureCredential()

# Create the transcription client
client = TranscriptionClient(endpoint=endpoint, credential=credential)

# Path to your audio file
importpathlib

audio_file_path = pathlib.Path(__file__).parent / "assets" / "audio.wav"

# Open and read the audio file
with open(audio_file_path, "rb") as audio_file:
 # Create transcription options
 options = TranscriptionOptions(locales=["en-US"]) # Specify the language

 # Create the request content
 request_content = TranscriptionContent(definition=options, audio=audio_file)

 # Transcribe the audio
 result = client.transcribe(request_content)

 # Print the transcription result
 print(f"Transcription: {result.combined_phrases[0].text}")

 # Print detailed phrase information
 if result.phrases:
 print("\nDetailed phrases:")
 for phrase in result.phrases:
 print(
 f" [{phrase.offset_milliseconds}ms - "
 f"{phrase.offset_milliseconds+phrase.duration_milliseconds}ms]: "
 f"{phrase.text}"
 )

Transcribe from a URL

fromazure.core.credentialsimport AzureKeyCredential
fromazure.ai.transcriptionimport TranscriptionClient
fromazure.ai.transcription.modelsimport TranscriptionOptions

# Get configuration from environment variables
endpoint = os.environ["AZURE_SPEECH_ENDPOINT"]

# We recommend using role-based access control (RBAC) for production scenarios
api_key = os.environ.get("AZURE_SPEECH_API_KEY")
if api_key:
 credential = AzureKeyCredential(api_key)
else:
 fromazure.identityimport DefaultAzureCredential

 credential = DefaultAzureCredential()

# Create the transcription client
client = TranscriptionClient(endpoint=endpoint, credential=credential)

# URL to your audio file (must be publicly accessible)
audio_url = "https://example.com/path/to/audio.wav"
# Configure transcription options
options = TranscriptionOptions(locales=["en-US"])

# Transcribe the audio from URL
# The service will access and transcribe the audio directly from the URL
result = client.transcribe_from_url(audio_url, options=options)

# Print the transcription result
print(f"Transcription: {result.combined_phrases[0].text}")

# Print duration information
if result.duration_milliseconds:
 print(f"Audio duration: {result.duration_milliseconds/1000:.2f} seconds")

Transcribe with enhanced mode

Enhanced mode provides advanced capabilities such as translation or summarization during transcription:

fromazure.core.credentialsimport AzureKeyCredential
fromazure.ai.transcriptionimport TranscriptionClient
fromazure.ai.transcription.modelsimport (
 TranscriptionContent,
 TranscriptionOptions,
 EnhancedModeProperties,
)

# Get configuration from environment variables
endpoint = os.environ["AZURE_SPEECH_ENDPOINT"]

# We recommend using role-based access control (RBAC) for production scenarios
api_key = os.environ.get("AZURE_SPEECH_API_KEY")
if api_key:
 credential = AzureKeyCredential(api_key)
else:
 fromazure.identityimport DefaultAzureCredential

 credential = DefaultAzureCredential()

# Create the transcription client
client = TranscriptionClient(endpoint=endpoint, credential=credential)

# Path to your audio file
audio_file_path = pathlib.Path(__file__).parent / "assets" / "audio.wav"

# Open and read the audio file
with open(audio_file_path, "rb") as audio_file:
 # Enhanced mode is automatically enabled when task is specified
 enhanced_mode = EnhancedModeProperties(task="transcribe")

 # Create transcription options with enhanced mode
 options = TranscriptionOptions(enhanced_mode=enhanced_mode)

 # Create the request content
 request_content = TranscriptionContent(definition=options, audio=audio_file)

 # Transcribe the audio with enhanced mode
 result = client.transcribe(request_content)

 # Print the transcription result
 print(result.combined_phrases[0].text)

Using async client

The library also provides an async client for asynchronous operations:

fromazure.core.credentialsimport AzureKeyCredential
fromazure.ai.transcription.aioimport TranscriptionClient
fromazure.ai.transcription.modelsimport TranscriptionContent, TranscriptionOptions

# Get configuration from environment variables
endpoint = os.environ["AZURE_SPEECH_ENDPOINT"]

# We recommend using role-based access control (RBAC) for production scenarios
api_key = os.environ.get("AZURE_SPEECH_API_KEY")
if api_key:
 credential = AzureKeyCredential(api_key)
else:
 fromazure.identity.aioimport DefaultAzureCredential

 credential = DefaultAzureCredential()

# Create the transcription client
async with TranscriptionClient(endpoint=endpoint, credential=credential) as client:
 # Path to your audio file
 importpathlib

 audio_file_path = pathlib.Path(__file__).parent.parent / "assets" / "audio.wav"

 # Open and read the audio file
 with open(audio_file_path, "rb") as audio_file:
 # Create transcription options
 options = TranscriptionOptions(locales=["en-US"]) # Specify the language

 # Create the request content
 request_content = TranscriptionContent(definition=options, audio=audio_file)

 # Transcribe the audio
 result = await client.transcribe(request_content)

 # Print the transcription result
 print(f"Transcription: {result.combined_phrases[0].text}")

 # Print detailed phrase information
 if result.phrases:
 print("\nDetailed phrases:")
 for phrase in result.phrases:
 print(
 f" [{phrase.offset_milliseconds}ms - "
 f"{phrase.offset_milliseconds+phrase.duration_milliseconds}ms]: "
 f"{phrase.text}"
 )

Troubleshooting

General

Azure AI Speech Transcription client library will raise exceptions defined in Azure Core if you call .raise_for_status() on your responses.

Logging

This library uses the standard logging library for logging. Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO level.

Detailed DEBUG level logging, including request/response bodies and unredacted headers, can be enabled on the client or per-operation with the logging_enable keyword argument.

importsys
importlogging
fromazure.core.credentialsimport AzureKeyCredential
fromazure.ai.transcriptionimport TranscriptionClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Enable network trace logging
endpoint = "https://<your-region>.api.cognitive.microsoft.com"
credential = AzureKeyCredential("<your-api-key>")
client = TranscriptionClient(endpoint=endpoint, credential=credential, logging_enable=True)

Errors and exceptions

When you interact with the Azure AI Speech Transcription client library using the Python SDK, errors returned by the service correspond to the same HTTP status codes returned for REST API requests.

For example, if you try to use an invalid API key, a 401 error is returned, indicating "Unauthorized".

fromazure.core.credentialsimport AzureKeyCredential
fromazure.ai.transcriptionimport TranscriptionClient
fromazure.core.exceptionsimport HttpResponseError

endpoint = "https://<your-region>.api.cognitive.microsoft.com"
credential = AzureKeyCredential("invalid_key")

client = TranscriptionClient(endpoint=endpoint, credential=credential)

try:
 # Attempt an operation
 pass
except HttpResponseError as e:
 print(f"Error: {e}")

Next steps

More sample code

For more extensive examples of using the Azure AI Speech Transcription client library, see the samples directory. These samples demonstrate:

• Basic transcription of audio files and URLs (sync and async)
• Speaker diarization to identify different speakers
• Multi-language detection and transcription
• Profanity filtering options
• Custom phrase lists for domain-specific terminology

Additional resources:

• Check the Azure AI Speech documentation for comprehensive tutorials and guides
• Explore the Azure SDK for Python samples repository

Additional documentation

For more extensive documentation on Azure AI Speech, see the Speech service documentation on docs.microsoft.com.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Release History

1.0.0 (2026-05-18)

Features Added

• First stable release of the Azure AI Transcription client library for Python.

1.0.0b4 (2026-04-20)

Other Changes

• Moved the package to a new service category folder transcription.

1.0.0b3 (2026-02-04)

Features Added

• Enhanced Mode now automatically sets enabled=True when task, target_language, or prompt are specified

Bugs Fixed

• Fixed Enhanced Mode not being activated when using EnhancedModeProperties without explicitly setting enabled=True

1.0.0b2 (2025-12-19)

Bugs Fixed

• Fixed API reference link

1.0.0b1 (2025-12-03)

Other Changes

• Initial version

Verified details

These details have been verified by PyPI

Maintainers

👁 Avatar for microsoft from gravatar.com
microsoft

Unverified details

These details have not been verified by PyPI

Project links

• repository

• Download URL: azure_ai_transcription-1.0.0.tar.gz
• Upload date: May 18, 2026
• Size: 66.9 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: RestSharp/106.13.0.0

Hashes for azure_ai_transcription-1.0.0.tar.gz

Algorithm	Hash digest
SHA256	90015d325f5fd5138fa2e9a8334dad50890be317f2082537d74cc675ae22e52d
MD5	eb12291df5b867caa9a3575f3eda63d3
BLAKE2b-256	98d53bf7022de372433c173b5dafd5fb1c88347758589058bc4a32c100d32ec9

See more details on using hashes here.

• Download URL: azure_ai_transcription-1.0.0-py3-none-any.whl
• Upload date: May 18, 2026
• Size: 62.6 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: RestSharp/106.13.0.0

Hashes for azure_ai_transcription-1.0.0-py3-none-any.whl

Algorithm	Hash digest
SHA256	5b4c9775db8c154828c790dff17b393d42b5679c6fc05de8e1d4e7532398dd60
MD5	8c78e16273ef6fba16d15356d4f7c0b6
BLAKE2b-256	adf6456c2d2febf1369a79a5c5048912cf66fe4569a7e74687e528b00b40ad82

See more details on using hashes here.