microsoft/semantic-kernel · critical · ServiceInitializationError

The OpenAI realtime model ID is required.

Error message

The OpenAI realtime model ID is required.

What it means

Raised during OpenAIRealtimeWebRTC construction when the resolved OpenAISettings has a falsy realtime_model_id. After settings are successfully created, the constructor verifies a realtime model name exists — every WebRTC realtime session requires a model id to negotiate the connection.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/open_ai_realtime.py:100

                This can include:
                kernel (Kernel): the kernel to use for function calls
                plugins (list[object] or dict[str, object]): the plugins to use for function calls
                settings (OpenAIRealtimeExecutionSettings): the settings to use for the session
                chat_history (ChatHistory): the chat history to use for the session
                Otherwise they can also be passed to the context manager.
        """
        try:
            openai_settings = OpenAISettings(
                api_key=api_key,
                org_id=org_id,
                realtime_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.realtime_model_id:
            raise ServiceInitializationError("The OpenAI realtime model ID is required.")
        if audio_track:
            kwargs["audio_track"] = audio_track
        super().__init__(
            audio_output_callback=audio_output_callback,
            ai_model_id=openai_settings.realtime_model_id,
            service_id=service_id,
            api_key=openai_settings.api_key.get_secret_value() if openai_settings.api_key else None,
            org_id=openai_settings.org_id,
            ai_model_type=OpenAIModelTypes.REALTIME,
            default_headers=default_headers,
            client=client,
            **kwargs,
        )


# region Websocket

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set the OPENAI_REALTIME_MODEL_ID environment variable (e.g., gpt-4o-realtime-preview)
2. Pass ai_model_id explicitly: OpenAIRealtimeWebRTC(audio_track=track, ai_model_id='gpt-4o-realtime-preview')
3. Verify the .env file contains the realtime model key if loading from env

Example fix

# before
service = OpenAIRealtimeWebRTC(audio_track=track, api_key=key)
# after
service = OpenAIRealtimeWebRTC(
    audio_track=track,
    api_key=key,
    ai_model_id='gpt-4o-realtime-preview',
)

from semantic_kernel.connectors.ai.open_ai import OpenAISettings

settings = OpenAISettings()
if not settings.realtime_model_id:
    raise ValueError('OPENAI_REALTIME_MODEL_ID is not set')

from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError

try:
    service = OpenAIRealtimeWebRTC(audio_track=track)
except ServiceInitializationError as e:
    if 'realtime model ID' in str(e):
        raise  # deployment config issue

When it happens

Trigger: Instantiating OpenAIRealtimeWebRTC without passing ai_model_id AND without setting OPENAI_REALTIME_MODEL_ID in the environment or .env file. The realtime_model_id on OpenAISettings resolves to None or an empty string.

Common situations: Using the realtime API for the first time without adding the realtime model env var; the env var name differs from what OpenAISettings expects; passing ai_model_id as a positional argument that maps to the wrong parameter.

Related errors

• Failed to create OpenAI settings.
• OpenAI/Azure OpenAI configuration was not found.
• Session is required for SessionUpdateEvent
• Audio is required for InputAudioBufferAppendEvent
• Audio track not initialized

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