fix(gemini): support detail parameter for image resolution on Gemini 2.x models

docs/my-website/docs/providers/gemini.md

@@ -1562,13 +1562,18 @@ LiteLLM Supports the following image types passed in `url`
 
 ## Media Resolution Control (Images & Videos)
 
-For Gemini 3+ models, LiteLLM supports per-part media resolution control using OpenAI's `detail` parameter. This allows you to specify different resolution levels for individual images and videos in your request, whether using `image_url` or `file` content types.
+LiteLLM supports OpenAI's `detail` parameter for specifying the image resolution when using Gemini models. The behavior differs between Gemini versions:
+
+| Gemini Version | Resolution Control | Behavior |
+|----------------|-------------------|----------|
+| Gemini 3+ | Per-part | Each image/video can have its own `detail` setting |
+| Gemini 2.x (2.0, 2.5) | Global | The highest `detail` from all images is applied globally via `mediaResolution` in `generationConfig` |
 
 **Supported `detail` values:**
-- `"low"` - Maps to `media_resolution: "low"` (280 tokens for images, 70 tokens per frame for videos)
-- `"medium"` - Maps to `media_resolution: "medium"`
-- `"high"` - Maps to `media_resolution: "high"` (1120 tokens for images)
-- `"ultra_high"` - Maps to `media_resolution: "ultra_high"`
+- `"low"` - Maps to `MEDIA_RESOLUTION_LOW` (280 tokens for images, 70 tokens per frame for videos)
+- `"medium"` - Maps to `MEDIA_RESOLUTION_MEDIUM`
+- `"high"` - Maps to `MEDIA_RESOLUTION_HIGH` (1120 tokens for images)
+- `"ultra_high"` - Maps to `MEDIA_RESOLUTION_ULTRA_HIGH`
 - `"auto"` or `None` - Model decides optimal resolution (no `media_resolution` set)
 
 **Usage Examples:**
@@ -1605,8 +1610,9 @@ messages = [
     }
 ]
 
+# Works with both Gemini 2.x and 3+
 response = completion(
-    model="gemini/gemini-3-pro-preview",
+    model="gemini/gemini-2.5-flash",  # or gemini-3-pro-preview
     messages=messages,
 )
 ```
@@ -1647,7 +1653,9 @@ response = completion(
 </Tabs>
 
 :::info
-**Per-Part Resolution:** Each image or video in your request can have its own `detail` setting, allowing mixed-resolution requests (e.g., a high-res chart alongside a low-res icon). This feature works with both `image_url` and `file` content types, and is only available for Gemini 3+ models.
+**Gemini 3+ Per-Part Resolution:** Each image or video can have its own `detail` setting, allowing mixed-resolution requests (e.g., a high-res chart alongside a low-res icon). This works with both `image_url` and `file` content types.
+
+**Gemini 2.x Global Resolution:** When multiple images have different `detail` values, LiteLLM uses the highest resolution found and applies it globally via `mediaResolution` in `generationConfig` (e.g., if one image has `"low"` and another has `"high"`, all images will use `"high"`).
 :::
 
 ## Video Metadata Control

litellm/llms/vertex_ai/gemini/transformation.py

@@ -77,14 +77,68 @@ def _convert_detail_to_media_resolution_enum(
     return None
 
 
+def _get_highest_media_resolution(
+    current: Optional[str], new_detail: Optional[str]
+) -> Optional[str]:
+    """
+    Compare two media resolution values and return the highest one.
+    Resolution hierarchy: ultra_high > high > medium > low > None
+    """
+    resolution_priority = {"ultra_high": 4, "high": 3, "medium": 2, "low": 1}
+    current_priority = resolution_priority.get(current, 0) if current else 0
+    new_priority = resolution_priority.get(new_detail, 0) if new_detail else 0
+
+    if new_priority > current_priority:
+        return new_detail
+    return current
+
+
+def _extract_max_media_resolution_from_messages(
+    messages: List[AllMessageValues],
+) -> Optional[str]:
+    """
+    Extract the highest media resolution (detail) from image content in messages.
+
+    This is used to set the global media_resolution in generation_config for
+    Gemini 2.x models which don't support per-part media resolution.
+
+    Args:
+        messages: List of messages in OpenAI format
+
+    Returns:
+        The highest detail level found ("high", "low", or None)
+    """
+    max_resolution: Optional[str] = None
+    for msg in messages:
+        content = msg.get("content")
+        if isinstance(content, list):
+            for item in content:
+                if not isinstance(item, dict):
+                    continue
+                detail: Optional[str] = None
+                if item.get("type") == "image_url":
+                    image_url = item.get("image_url")
+                    if isinstance(image_url, dict):
+                        detail = image_url.get("detail")
+                elif item.get("type") == "file":
+                    file_obj = item.get("file")
+                    if isinstance(file_obj, dict):
+                        detail = file_obj.get("detail")
+                if detail:
+                    max_resolution = _get_highest_media_resolution(
+                        max_resolution, detail
+                    )
+    return max_resolution
+
+
 def _apply_gemini_3_metadata(
     part: PartType,
     model: Optional[str],
     media_resolution_enum: Optional[Dict[str, str]],
     video_metadata: Optional[Dict[str, Any]],
 ) -> PartType:
     """
-    Apply the unique media_resolution and video_metadata parameters of Gemini 3+    
+    Apply the unique media_resolution and video_metadata parameters of Gemini 3+
     """
     if model is None:
         return part
@@ -541,7 +595,7 @@ def _pop_and_merge_extra_body(data: RequestBody, optional_params: dict) -> None:
                 data_dict[k] = v
 
 
-def _transform_request_body(
+def _transform_request_body(  # noqa: PLR0915
     messages: List[AllMessageValues],
     model: str,
     optional_params: dict,
@@ -615,6 +669,19 @@ def _transform_request_body(
         generation_config: Optional[GenerationConfig] = GenerationConfig(
             **filtered_params
         )
+
+        # For Gemini 2.x models, add media_resolution to generation_config (global)
+        # Gemini 3+ supports per-part media_resolution, but 2.x only supports global
+        # Gemini 1.x does not support mediaResolution at all
+        if "gemini-2" in model:
+            max_media_resolution = _extract_max_media_resolution_from_messages(messages)
+            if max_media_resolution:
+                media_resolution_value = _convert_detail_to_media_resolution_enum(
+                    max_media_resolution
+                )
+                if media_resolution_value and generation_config is not None:
+                    generation_config["mediaResolution"] = media_resolution_value["level"]
+
         data = RequestBody(contents=content)
         if system_instructions is not None:
             data["system_instruction"] = system_instructions

litellm/types/llms/vertex_ai.py

@@ -214,6 +214,7 @@ class GenerationConfig(TypedDict, total=False):
     responseModalities: List[GeminiResponseModalities]
     imageConfig: GeminiImageConfig
     thinkingConfig: GeminiThinkingConfig
+    mediaResolution: str
     speechConfig: SpeechConfig