Support for aspect ratio control in image generation (gemini's nano-banana)

[aldensiol]

Description

Recently Gemini launched support for aspect ratio control during image generation.

Supported ratios include:

• Landscape: 21:9, 16:9, 4:3, 3:2
• Square: 1:1
• Portrait: 9:16, 3:4, 2:3
• Flexible: 5:4, 4:5

# code from google's documentation
response = client.models.generate_content(
    model="gemini-2.5-flash-image",
    contents=[prompt, image],
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
        )
    )
)

Perhaps the BinaryImage object could be updated to support an aspect_ratio (Optional[str]) arg

from pydantic_ai import BinaryImage

# just an example
nano_banana_agent = Agent(
    output_type=BinaryImage(aspect_ratio="16:9",
    **kwargs,
)

response = await nano_banana_agent.run(user_prompt="Generate a cartoony image of halloween")
# return base64 image in the desired aspect ratio
return response.output.data_uri

References

Blog from google dev: https://developers.googleblog.com/en/gemini-2-5-flash-image-now-ready-for-production-with-new-aspect-ratios/

[DouweM]

@aldensiol Thanks for the report! Would you be up for implementing this in a PR?

The most consistent way to support this would be to add an aspect_ratio field on the ImageGenerationTool (https://ai.pydantic.dev/builtin-tools/#image-generation-tool), which currently already supports a number of options for OpenAI:

pydantic-ai/pydantic_ai_slim/pydantic_ai/builtin_tools.py

Lines 146 to 224 in 3eaa11e

	@dataclass(kw_only=True)
	class ImageGenerationTool(AbstractBuiltinTool):
	"""A builtin tool that allows your agent to generate images.
	Supported by:
	* OpenAI Responses
	* Google
	"""
	background: Literal['transparent', 'opaque', 'auto'] = 'auto'
	"""Background type for the generated image.
	Supported by:
	* OpenAI Responses. 'transparent' is only supported for 'png' and 'webp' output formats.
	"""
	input_fidelity: Literal['high', 'low'] | None = None
	"""
	Control how much effort the model will exert to match the style and features,
	especially facial features, of input images.
	Supported by:
	* OpenAI Responses. Default: 'low'.
	"""
	moderation: Literal['auto', 'low'] = 'auto'
	"""Moderation level for the generated image.
	Supported by:
	* OpenAI Responses
	"""
	output_compression: int = 100
	"""Compression level for the output image.
	Supported by:
	* OpenAI Responses. Only supported for 'png' and 'webp' output formats.
	"""
	output_format: Literal['png', 'webp', 'jpeg'] | None = None
	"""The output format of the generated image.
	Supported by:
	* OpenAI Responses. Default: 'png'.
	"""
	partial_images: int = 0
	"""
	Number of partial images to generate in streaming mode.
	Supported by:
	* OpenAI Responses. Supports 0 to 3.
	"""
	quality: Literal['low', 'medium', 'high', 'auto'] = 'auto'
	"""The quality of the generated image.
	Supported by:
	* OpenAI Responses
	"""
	size: Literal['1024x1024', '1024x1536', '1536x1024', 'auto'] = 'auto'
	"""The size of the generated image.
	Supported by:
	* OpenAI Responses
	"""
	kind: str = 'image_generation'
	"""The kind of tool."""

We can then update GoogleModel._get_tools() to return a google.genai.types.ImageConfigDict alongside the list[ToolDict] if an ImageGenerationTool was found:

pydantic-ai/pydantic_ai_slim/pydantic_ai/models/google.py

Lines 315 to 345 in 3eaa11e

	def _get_tools(self, model_request_parameters: ModelRequestParameters) -> list[ToolDict] | None:
	tools: list[ToolDict] = [
	ToolDict(function_declarations=[_function_declaration_from_tool(t)])
	for t in model_request_parameters.tool_defs.values()
	]
	if model_request_parameters.builtin_tools:
	if model_request_parameters.output_tools:
	raise UserError(
	'Gemini does not support output tools and built-in tools at the same time. Use `output_type=PromptedOutput(...)` instead.'
	)
	if model_request_parameters.function_tools:
	raise UserError('Gemini does not support user tools and built-in tools at the same time.')
	for tool in model_request_parameters.builtin_tools:
	if isinstance(tool, WebSearchTool):
	tools.append(ToolDict(google_search=GoogleSearchDict()))
	elif isinstance(tool, UrlContextTool):
	tools.append(ToolDict(url_context=UrlContextDict()))
	elif isinstance(tool, CodeExecutionTool):
	tools.append(ToolDict(code_execution=ToolCodeExecutionDict()))
	elif isinstance(tool, ImageGenerationTool): # pragma: no branch
	if not self.profile.supports_image_output:
	raise UserError(
	"`ImageGenerationTool` is not supported by this model. Use a model with 'image' in the name instead."
	)
	else: # pragma: no cover
	raise UserError(
	f'`{tool.__class__.__name__}` is not supported by `GoogleModel`. If it should be, please file an issue.'
	)
	return tools or None

That ImageConfigDict can then be included in the GenerateContentConfigDict here:

pydantic-ai/pydantic_ai_slim/pydantic_ai/models/google.py

Lines 427 to 446 in 3eaa11e

	config = GenerateContentConfigDict(
	http_options=http_options,
	system_instruction=system_instruction,
	temperature=model_settings.get('temperature'),
	top_p=model_settings.get('top_p'),
	max_output_tokens=model_settings.get('max_tokens'),
	stop_sequences=model_settings.get('stop_sequences'),
	presence_penalty=model_settings.get('presence_penalty'),
	frequency_penalty=model_settings.get('frequency_penalty'),
	seed=model_settings.get('seed'),
	safety_settings=model_settings.get('google_safety_settings'),
	thinking_config=model_settings.get('google_thinking_config'),
	labels=model_settings.get('google_labels'),
	media_resolution=model_settings.get('google_video_resolution'),
	cached_content=model_settings.get('google_cached_content'),
	tools=cast(ToolListUnionDict, tools),
	tool_config=tool_config,
	response_mime_type=response_mime_type,
	response_schema=response_schema,
	)

I'm not sure the response_modalities=["IMAGE"] bit is required; image generation seems to work just fine without it, and we'd typically want to still allow the model to output text as well.

Note that the google-genai package will need to be updated to get the new ImageConfig type. While we're at it, we can also change "image-preview" in the model name in the docs to just "image", now that the model is production-ready.

[dzakyfw]

Thanks for opening this issue, Is there any update or timeline on when this might be available?

[DouweM]

@dzakyfw As soon as you or someone else submit a (AI-assisted) PR 😄