What causes "The OpenAI audio to text model ID is required." in microsoft/semantic-kernel?

Pass ai_model_id= explicitly: OpenAIAudioToText(ai_model_id='whisper-1', ...).

microsoft/semantic-kernel · error · ServiceInitializationError

The OpenAI audio to text model ID is required.

Error message

The OpenAI audio to text model ID is required.

What it means

Raised by OpenAIAudioToText.__init__ after settings creation succeeds but audio_to_text_model_id is empty or None. This field comes from the ai_model_id constructor argument or the OPENAI_AUDIO_TO_TEXT_MODEL_ID environment variable. The transcription service requires a model identifier (typically 'whisper-1') to know which model to invoke.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/open_ai_audio_to_text.py:60

            default_headers: The default headers mapping of string keys to
                string values for HTTP requests. (Optional)
            async_client: An existing client to use. (Optional)
            env_file_path: Use the environment settings file as
                a fallback to environment variables. (Optional)
            env_file_encoding: The encoding of the environment settings file. (Optional)
        """
        try:
            openai_settings = OpenAISettings(
                api_key=api_key,
                org_id=org_id,
                audio_to_text_model_id=ai_model_id,
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
            )
        except ValidationError as ex:
            raise ServiceInitializationError("Failed to create OpenAI settings.", ex) from ex
        if not openai_settings.audio_to_text_model_id:
            raise ServiceInitializationError("The OpenAI audio to text model ID is required.")
        super().__init__(
            ai_model_id=openai_settings.audio_to_text_model_id,
            api_key=openai_settings.api_key.get_secret_value() if openai_settings.api_key else None,
            ai_model_type=OpenAIModelTypes.AUDIO_TO_TEXT,
            org_id=openai_settings.org_id,
            service_id=service_id,
            default_headers=default_headers,
            client=async_client,
        )

    @classmethod
    def from_dict(cls: type[T_], settings: dict[str, Any]) -> T_:
        """Initialize an Open AI service from a dictionary of settings.

        Args:
            settings: A dictionary of settings for the service.
        """
        return cls(

View on GitHub (pinned to c028a0c7dc)

Solutions

Pass ai_model_id= explicitly: OpenAIAudioToText(ai_model_id='whisper-1', ...).
Set OPENAI_AUDIO_TO_TEXT_MODEL_ID=whisper-1 in your environment or .env file.
Verify the model name is correct per https://platform.openai.com/docs/models.

Example fix

# before
service = OpenAIAudioToText(
    api_key='sk-...',
)
# after
service = OpenAIAudioToText(
    ai_model_id='whisper-1',
    api_key='sk-...',
)

Defensive patterns

Strategy: validation

Validate before calling

import os

model_id = os.environ.get('OPENAI_AUDIO_TO_TEXT_MODEL_ID')
if not model_id:
    raise ValueError(
        'OPENAI_AUDIO_TO_TEXT_MODEL_ID is not set (e.g. "whisper-1"). '
        'Set it in your environment or .env file, or pass ai_model_id= to the constructor.'
    )

Try / catch

from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError

try:
    service = OpenAIAudioToText(
        ai_model_id=os.environ.get('OPENAI_AUDIO_TO_TEXT_MODEL_ID'),
        api_key=os.environ.get('OPENAI_API_KEY'),
    )
except ServiceInitializationError as e:
    if 'audio to text model ID is required' in str(e):
        print('Set OPENAI_AUDIO_TO_TEXT_MODEL_ID or pass ai_model_id=')
    raise

Prevention

Set OPENAI_AUDIO_TO_TEXT_MODEL_ID (e.g. whisper-1) in your environment or .env file.
Always pass ai_model_id= explicitly in the constructor.
Use the audio-to-text-specific env var, not a generic model ID.
Check https://platform.openai.com/docs/models for valid model names.

When it happens

Trigger: Constructing OpenAIAudioToText without ai_model_id= and without OPENAI_AUDIO_TO_TEXT_MODEL_ID set in the environment or .env file. The api_key resolved (or async_client was passed), but no model identifier was provided.

Common situations: Using OPENAI_MODEL_ID (generic) instead of OPENAI_AUDIO_TO_TEXT_MODEL_ID (specific); .env file present but the audio_to_text model line missing; running in a fresh environment without the model env var; assuming the constructor has a default model (it does not).

Related errors

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