{"record":{"id":"d9695aba847b58ea","repo":"microsoft/semantic-kernel","slug":"the-azure-openai-audio-to-text-deployment-name-is","errorCode":null,"errorMessage":"The Azure OpenAI audio to text deployment name is required.","messagePattern":"The Azure OpenAI audio to text deployment name is required\\.","errorType":"exception","errorClass":"ServiceInitializationError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/ai/open_ai/services/azure_audio_to_text.py","lineNumber":79,"sourceCode":"                environment variables. (Optional)\n            env_file_encoding: The encoding of the environment settings file. (Optional)\n            credential: The credential to use for authentication. (Optional)\n        \"\"\"\n        try:\n            azure_openai_settings = AzureOpenAISettings(\n                env_file_path=env_file_path,\n                env_file_encoding=env_file_encoding,\n                api_key=api_key,\n                audio_to_text_deployment_name=deployment_name,\n                endpoint=endpoint,\n                base_url=base_url,\n                api_version=api_version,\n                token_endpoint=token_endpoint,\n            )\n        except ValidationError as exc:\n            raise ServiceInitializationError(f\"Invalid settings: {exc}\") from exc\n        if not azure_openai_settings.audio_to_text_deployment_name:\n            raise ServiceInitializationError(\"The Azure OpenAI audio to text deployment name is required.\")\n\n        super().__init__(\n            deployment_name=azure_openai_settings.audio_to_text_deployment_name,\n            endpoint=azure_openai_settings.endpoint,\n            base_url=azure_openai_settings.base_url,\n            api_version=azure_openai_settings.api_version,\n            service_id=service_id,\n            api_key=azure_openai_settings.api_key.get_secret_value() if azure_openai_settings.api_key else None,\n            ad_token=ad_token,\n            ad_token_provider=ad_token_provider,\n            token_endpoint=azure_openai_settings.token_endpoint,\n            default_headers=default_headers,\n            ai_model_type=OpenAIModelTypes.AUDIO_TO_TEXT,\n            client=async_client,\n            credential=credential,\n        )\n\n    @classmethod","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/ai/open_ai/services/azure_audio_to_text.py#L61-L97","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass deployment_name explicitly: AzureOpenAIAudioToTextService(deployment_name='whisper-deployment', ...).","Set the AZURE_OPENAI_AUDIO_TO_TEXT_DEPLOYMENT_NAME environment variable in your .env file or shell.","Verify the deployment name matches an actual Whisper deployment in your Azure OpenAI resource."],"exampleFix":"// before\nservice = AzureOpenAIAudioToTextService(endpoint='...', api_key='...')  # no deployment_name\n// after\nservice = AzureOpenAIAudioToTextService(\n    deployment_name='whisper',\n    endpoint='https://my-resource.openai.azure.com/',\n    api_key='...'\n)","handlingStrategy":"validation","validationCode":"def validate_audio_to_text_deployment_name(deployment_name: str | None) -> None:\n    if not deployment_name:\n        import os\n        if not os.environ.get('AZURE_OPENAI_AUDIO_TO_TEXT_DEPLOYMENT_NAME'):\n            raise ValueError(\n                'audio_to_text deployment name is required. '\n                'Pass deployment_name or set AZURE_OPENAI_AUDIO_TO_TEXT_DEPLOYMENT_NAME.'\n            )","typeGuard":"def has_audio_to_text_deployment_name(deployment_name: str | None) -> bool:\n    import os\n    return bool(deployment_name or os.environ.get('AZURE_OPENAI_AUDIO_TO_TEXT_DEPLOYMENT_NAME'))","tryCatchPattern":"from semantic_kernel.exceptions import ServiceInitializationError\n\ntry:\n    service = AzureOpenAIAudioToTextService(...)\nexcept ServiceInitializationError as e:\n    if 'deployment name is required' in str(e):\n        service = AzureOpenAIAudioToTextService(deployment_name='whisper', ...)","preventionTips":["Always pass deployment_name explicitly or set the AZURE_OPENAI_AUDIO_TO_TEXT_DEPLOYMENT_NAME env var.","Verify the deployment exists in your Azure OpenAI resource portal.","Centralize deployment names in a config file validated at startup."],"tags":["azure-openai","audio-to-text","deployment-name","initialization","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}