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

[Chesars]

Title

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

Relevant issues

Fixes #17084

Pre-Submission checklist

• I have Added testing in the tests/litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem

Type

🐛 Bug Fix
📖 Documentation

Summary

Add global media_resolution support for Gemini 2.x models (2.0, 2.5) when using OpenAI's detail parameter on images.

Previously, the detail parameter was only working for Gemini 3+ models (per-part) and did not work for other Gemini models.

Example Request

import litellm

response = litellm.completion(
    model="gemini/gemini-2.5-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "data:image/png;base64,iVBORw0KGgo...",
                        "detail": "high"  # Now translated to mediaResolution for Gemini 2.x
                    }
                }
            ]
        }
    ]
)

Changes

• Add _get_highest_media_resolution() to compare resolution levels
• Add _extract_max_media_resolution_from_messages() to extract highest detail from all images
• Update _transform_request_body() to add mediaResolution to generationConfig for Gemini 2.x models

Tests Added

✅ test_transform_request_body_gemini_2x_adds_media_resolution
✅ test_extract_max_media_resolution_multiple_images_mixed
✅ test_get_highest_media_resolution_high_wins

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Error		Mar 4, 2026 8:33pm

[ghost]

@Chesars can you please fix this linting error?

[Chesars]

@Chesars can you please fix this linting error?

Hi fixed in 01bfc2e

[greptile-apps]

Greptile Summary

This PR adds support for OpenAI's detail parameter on image/file content parts when using Gemini 2.x models (2.0, 2.5). Previously, the detail → mediaResolution translation only worked for Gemini 3+ (per-part). For Gemini 2.x, LiteLLM now extracts the highest detail value across all images/files in the message and sets it as a global mediaResolution in generationConfig.

• Adds _get_highest_media_resolution() to compare resolution priority levels (ultra_high > high > medium > low > None)
• Adds _extract_max_media_resolution_from_messages() to scan both image_url and file content types for the highest detail
• Applies global mediaResolution in _transform_request_body() only for Gemini 2.x models (via "gemini-2" in model check)
• Adds mediaResolution field to the GenerationConfig TypedDict
• Includes 13 comprehensive unit tests covering priority ordering, multiple content types, and model version gating
• Updates docs with a clear version comparison table for media resolution behavior

Confidence Score: 4/5

• This PR is safe to merge — it adds a well-scoped feature with comprehensive tests and no backwards-incompatible changes.
• The implementation is clean and well-tested. The "gemini-2" in model check correctly scopes the feature to only Gemini 2.x models, avoiding interference with 1.x and 3.x models. Resolution priority logic correctly handles all documented detail values including edge cases like "auto" and None. The only concern (hardcoded model check) was already raised in prior review threads and follows existing patterns in the codebase.
• litellm/llms/vertex_ai/gemini/transformation.py — the hardcoded "gemini-2" in model check was flagged in prior threads; all other files are straightforward.

Important Files Changed

Filename	Overview
litellm/llms/vertex_ai/gemini/transformation.py	Adds _get_highest_media_resolution and _extract_max_media_resolution_from_messages helper functions, and integrates global mediaResolution into generationConfig for Gemini 2.x models. Logic is correct and handles edge cases (auto, None, file types). The "gemini-2" in model check follows existing patterns but is hardcoded (previously flagged).
litellm/types/llms/vertex_ai.py	Adds mediaResolution: str field to GenerationConfig TypedDict. Minimal, correct change.
tests/test_litellm/llms/vertex_ai/gemini/test_vertex_ai_gemini_transformation.py	Comprehensive test suite covering priority ordering, extraction from image_url and file types, Gemini 2.x/3.x/1.x model behavior, and edge cases. All tests are mock-based with no real network calls.
docs/my-website/docs/providers/gemini.md	Updated documentation to describe both per-part (Gemini 3+) and global (Gemini 2.x) media resolution behavior, with a clear version comparison table.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User sends messages with detail param] --> B{Model version?}
    B -->|"gemini-3" in model| C[Per-part: _apply_gemini_3_metadata\nsets media_resolution on each part]
    B -->|"gemini-2" in model| D[_extract_max_media_resolution_from_messages]
    B -->|"gemini-1.x"| E[No mediaResolution support]
    D --> F{Scan all content parts}
    F --> G[image_url parts]
    F --> H[file parts]
    G --> I[Extract detail value]
    H --> I
    I --> J[_get_highest_media_resolution\nCompare priorities:\nultra_high=4, high=3, medium=2, low=1]
    J --> K{max_resolution found?}
    K -->|Yes| L[_convert_detail_to_media_resolution_enum]
    K -->|No / auto| M[No mediaResolution set]
    L --> N[Set generationConfig.mediaResolution\nglobally for all parts]

Loading

_{Last reviewed commit: c1a8bdd}