microsoft/semantic-kernel · error · ServiceInitializationError

The Azure OpenAI audio to text deployment name is required.

Error message

The Azure OpenAI audio to text deployment name is required.

What it means

After AzureOpenAISettings is successfully validated, the AzureOpenAIAudioToTextService constructor checks that audio_to_text_deployment_name is set (truthy). If it's empty or None — either because deployment_name wasn't passed and no AZURE_OPENAI_AUDIO_TO_TEXT_DEPLOYMENT_NAME env var exists — it raises ServiceInitializationError. This is distinct from a pydantic validation failure; the field exists but is empty.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/azure_audio_to_text.py:79

                environment variables. (Optional)
            env_file_encoding: The encoding of the environment settings file. (Optional)
            credential: The credential to use for authentication. (Optional)
        """
        try:
            azure_openai_settings = AzureOpenAISettings(
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
                api_key=api_key,
                audio_to_text_deployment_name=deployment_name,
                endpoint=endpoint,
                base_url=base_url,
                api_version=api_version,
                token_endpoint=token_endpoint,
            )
        except ValidationError as exc:
            raise ServiceInitializationError(f"Invalid settings: {exc}") from exc
        if not azure_openai_settings.audio_to_text_deployment_name:
            raise ServiceInitializationError("The Azure OpenAI audio to text deployment name is required.")

        super().__init__(
            deployment_name=azure_openai_settings.audio_to_text_deployment_name,
            endpoint=azure_openai_settings.endpoint,
            base_url=azure_openai_settings.base_url,
            api_version=azure_openai_settings.api_version,
            service_id=service_id,
            api_key=azure_openai_settings.api_key.get_secret_value() if azure_openai_settings.api_key else None,
            ad_token=ad_token,
            ad_token_provider=ad_token_provider,
            token_endpoint=azure_openai_settings.token_endpoint,
            default_headers=default_headers,
            ai_model_type=OpenAIModelTypes.AUDIO_TO_TEXT,
            client=async_client,
            credential=credential,
        )

    @classmethod

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass deployment_name explicitly: AzureOpenAIAudioToTextService(deployment_name='whisper-deployment', ...).
2. Set the AZURE_OPENAI_AUDIO_TO_TEXT_DEPLOYMENT_NAME environment variable in your .env file or shell.
3. Verify the deployment name matches an actual Whisper deployment in your Azure OpenAI resource.

Example fix

// before
service = AzureOpenAIAudioToTextService(endpoint='...', api_key='...')  # no deployment_name
// after
service = AzureOpenAIAudioToTextService(
    deployment_name='whisper',
    endpoint='https://my-resource.openai.azure.com/',
    api_key='...'
)

def validate_audio_to_text_deployment_name(deployment_name: str | None) -> None:
    if not deployment_name:
        import os
        if not os.environ.get('AZURE_OPENAI_AUDIO_TO_TEXT_DEPLOYMENT_NAME'):
            raise ValueError(
                'audio_to_text deployment name is required. '
                'Pass deployment_name or set AZURE_OPENAI_AUDIO_TO_TEXT_DEPLOYMENT_NAME.'
            )

def has_audio_to_text_deployment_name(deployment_name: str | None) -> bool:
    import os
    return bool(deployment_name or os.environ.get('AZURE_OPENAI_AUDIO_TO_TEXT_DEPLOYMENT_NAME'))

from semantic_kernel.exceptions import ServiceInitializationError

try:
    service = AzureOpenAIAudioToTextService(...)
except ServiceInitializationError as e:
    if 'deployment name is required' in str(e):
        service = AzureOpenAIAudioToTextService(deployment_name='whisper', ...)

When it happens

Trigger: Constructing AzureOpenAIAudioToTextService without deployment_name and without the AZURE_OPENAI_AUDIO_TO_TEXT_DEPLOYMENT_NAME environment variable; passing deployment_name=None or deployment_name='' explicitly.

Common situations: New deployment where the env var hasn't been set yet; typo in the env var name; using a shared settings file that has chat/text deployments but not the audio-to-text one; assuming the deployment name is optional.

Related errors

• Please provide an Azure OpenAI Responses deployment name
• Invalid settings: {exc}
• chat_deployment_name is required.
• Expected AzureOpenAISettings, got {type(settings).__name__}
• Failed to create Azure OpenAI settings: {exc}

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/d9695aba847b58ea. Report an issue: GitHub.