Add 'resolution' config to ImageGenerationTool

Author: h0rv

docs/builtin-tools.md

@@ -353,6 +353,23 @@ assert isinstance(result.output, BinaryImage)
 
 _(This example is complete, it can be run "as is")_
 
+To control the image resolution with Gemini 3 Pro Image models, use the `resolution` parameter:
+
+```py {title="image_generation_google_resolution.py"}
+from pydantic_ai import Agent, BinaryImage, ImageGenerationTool
+
+agent = Agent(
+    'google-gla:gemini-3-pro-image-preview',
+    builtin_tools=[ImageGenerationTool(aspect_ratio='16:9', resolution='4K')],
+    output_type=BinaryImage,
+)
+
+result = agent.run_sync('Generate a high-resolution wide landscape illustration of an axolotl.')
+assert isinstance(result.output, BinaryImage)
+```
+
+_(This example is complete, it can be run "as is")_
+
 For more details, check the [API documentation][pydantic_ai.builtin_tools.ImageGenerationTool].
 
 #### Provider Support
@@ -368,6 +385,7 @@ For more details, check the [API documentation][pydantic_ai.builtin_tools.ImageG
 | `quality` | ✅ | ❌ |
 | `size` | ✅ | ❌ |
 | `aspect_ratio` | ✅ (1:1, 2:3, 3:2) | ✅ |
+| `resolution` | ❌ | ✅ (1K, 2K, 4K) |
 
 ## Web Fetch Tool
 

pydantic_ai_slim/pydantic_ai/builtin_tools.py

@@ -328,6 +328,14 @@ class ImageGenerationTool(AbstractBuiltinTool):
     * OpenAI Responses (maps '1:1', '2:3', and '3:2' to supported sizes)
     """
 
+    resolution: str | None = None
+    """The resolution/size tier for generated images.
+
+    Supported by:
+
+    * Google: '1K', '2K', '4K' for Gemini 3 Pro Image and compatible models
+    """
+
     kind: str = 'image_generation'
     """The kind of tool."""
 

pydantic_ai_slim/pydantic_ai/models/google.py

@@ -362,8 +362,14 @@ def _get_tools(
                         raise UserError(
                             "`ImageGenerationTool` is not supported by this model. Use a model with 'image' in the name instead."
                         )
-                    if tool.aspect_ratio:
-                        image_config = ImageConfigDict(aspect_ratio=tool.aspect_ratio)
+                    # Build image_config from tool parameters, only including non-None values
+                    image_config_kwargs: dict[str, Any] = {}
+                    if tool.aspect_ratio is not None:
+                        image_config_kwargs['aspect_ratio'] = tool.aspect_ratio
+                    if tool.resolution is not None:
+                        image_config_kwargs['image_size'] = tool.resolution
+                    if image_config_kwargs:
+                        image_config = ImageConfigDict(**image_config_kwargs)
                 else:  # pragma: no cover
                     raise UserError(
                         f'`{tool.__class__.__name__}` is not supported by `GoogleModel`. If it should be, please file an issue.'

tests/models/test_google.py

@@ -3652,6 +3652,26 @@ async def test_google_image_generation_tool_aspect_ratio(google_provider: Google
     assert image_config == {'aspect_ratio': '16:9'}
 
 
+async def test_google_image_generation_resolution(google_provider: GoogleProvider) -> None:
+    """Test that resolution parameter from ImageGenerationTool is added to image_config."""
+    model = GoogleModel('gemini-3-pro-image-preview', provider=google_provider)
+    params = ModelRequestParameters(builtin_tools=[ImageGenerationTool(resolution='2K')])
+
+    tools, image_config = model._get_tools(params)  # pyright: ignore[reportPrivateUsage]
+    assert tools is None
+    assert image_config == {'image_size': '2K'}
+
+
+async def test_google_image_generation_resolution_with_aspect_ratio(google_provider: GoogleProvider) -> None:
+    """Test that resolution and aspect_ratio from ImageGenerationTool work together."""
+    model = GoogleModel('gemini-3-pro-image-preview', provider=google_provider)
+    params = ModelRequestParameters(builtin_tools=[ImageGenerationTool(aspect_ratio='16:9', resolution='4K')])
+
+    tools, image_config = model._get_tools(params)  # pyright: ignore[reportPrivateUsage]
+    assert tools is None
+    assert image_config == {'aspect_ratio': '16:9', 'image_size': '4K'}
+
+
 async def test_google_vertexai_image_generation(allow_model_requests: None, vertex_provider: GoogleProvider):
     model = GoogleModel('gemini-2.5-flash-image', provider=vertex_provider)