Repository: livekit/agents
File: livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py (Python)

Code before:
    resize_options=images.ResizeOptions(width=1024, height=1024, strategy="scale_aspect_fit"),
)

lk_google_debug = int(os.getenv("LK_GOOGLE_DEBUG", 0))


def _get_model_mismatch_hint(model: str, use_vertexai: bool, error_message: str) -> str | None:
    """
    Generate a helpful hint when a WebSocket 1008 error suggests model/API mismatch.

    Args:
        model: The model name being used
        use_vertexai: Whether VertexAI is enabled
        error_message: The error message from the WebSocket exception

    Returns:
        A helpful hint string, or None if no mismatch detected
    """
    # Only provide hints for 1008 policy violations
    if "1008" not in error_message and "policy violation" not in error_message.lower():
        return None

    is_vertexai_model = model.startswith("gemini-live-")
    is_gemini_api_model = model.startswith(("gemini-2.", "gemini-1."))

    if use_vertexai and is_gemini_api_model:
        suggested_model = None
        if "09-2025" in model:
            suggested_model = "gemini-live-2.5-flash-preview-native-audio-09-2025"
        elif "12-2025" in model or "2.5" in model:
            suggested_model = "gemini-live-2.5-flash-native-audio"

        hint = (
            f"\n\nHint: Model '{model}' appears to be a Gemini API model, but VertexAI is enabled. "
            f"VertexAI requires different model names (prefixed with 'gemini-live-')."
        )
        if suggested_model:
            hint += f" Try using model='{suggested_model}' instead."
        return hint

    if not use_vertexai and is_vertexai_model:
        suggested_model = None
        if "09-2025" in model:
            suggested_model = "gemini-2.5-flash-native-audio-preview-09-2025"
        elif "preview" not in model:
            suggested_model = "gemini-2.5-flash-native-audio-preview-12-2025"

        hint = (
            f"\n\nHint: Model '{model}' appears to be a VertexAI model, but Gemini API is being used. "
            f"Gemini API requires different model names."
        )

Review comment (suggestion):
this logic doesn't seem very robust. we do not know how google is going to name their future models.

if you intend to do this, I would suggest:
- keeping a list known of vertex models and another list of gemini
- when specifically detect for mismatch, and throw an exception if a user is using vertext with gemini and vice versa

alternatively, translating the error code and log a clear message (this model isn't supported)

Code after:
    resize_options=images.ResizeOptions(width=1024, height=1024, strategy="scale_aspect_fit"),
)

lk_google_debug = int(os.getenv("LK_GOOGLE_DEBUG", 0))

# Known VertexAI models for the Live API
# See: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/live-api
KNOWN_VERTEXAI_MODELS: frozenset[str] = frozenset(
    {
        "gemini-live-2.5-flash-native-audio",
        "gemini-live-2.5-flash-preview-native-audio-09-2025",
        "gemini-live-2.5-flash-preview-native-audio",
    }
)

# Known Gemini API models for the Live API
# See: https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-live
KNOWN_GEMINI_API_MODELS: frozenset[str] = frozenset(
    {
        "gemini-2.5-flash-native-audio-preview-12-2025",
        "gemini-2.5-flash-native-audio-preview-09-2025",
        "gemini-2.0-flash-exp",
    }
)


def _validate_model_api_match(model: str, use_vertexai: bool) -> None:
    """
    Validate that the model name matches the API being used.

    Raises ValueError if a known model is used with the wrong API configuration.

    Args:
        model: The model name being used
        use_vertexai: Whether VertexAI is enabled
    """
    if use_vertexai and model in KNOWN_GEMINI_API_MODELS:
        raise ValueError(
            f"Model '{model}' is a Gemini API model, but vertexai=True. "
            f"Use a VertexAI model (e.g., 'gemini-live-2.5-flash-native-audio') "
            f"or set vertexai=False."
        )

    if not use_vertexai and model in KNOWN_VERTEXAI_MODELS:
        raise ValueError(
            f"Model '{model}' is a VertexAI model, but vertexai=False. "
            f"Use a Gemini API model (e.g., 'gemini-2.5-flash-native-audio-preview-12-2025') "
            f"or set vertexai=True."
        )