# generate_image: aspectRatio parameter support for gemini-3-pro-image

**Date:** 2026-05-06

## Problem

Users could not generate 3:4 aspect ratio images using `gemini-3-pro-image` from the chat input box. The `generate_image` tool schema used `additionalProperties: false` and only exposed a `size` enum with pixel-dimension strings. None of the sizes in the enum represented an exact 3:4 ratio, and the schema blocked the AI agent from passing the `aspectRatio` parameter that Gemini image models require.

## Root Cause

Two files defined the `generate_image` tool schema:

- `packages/runner-harness/src/tools/image-generate.ts` (used by claude runner / daemon)
- `packages/runner-pi/src/image-tools.ts` (used by pi runner)

Both had:
1. A `size` enum with no 3:4 ratio sizes (nearest were `1056x1568` ≈ 2:3 and `1088x1472` ≈ 3:4.05 — neither exact)
2. No `aspectRatio` field — so `additionalProperties: false` caused the LLM to never pass it
3. No `aspect_ratio` forwarded in the API request body to the proxy/LiteLLM

When using `gemini-3-pro-image` through an OpenAI-compatible proxy (e.g. LiteLLM), the Gemini Image API requires `aspectRatio` (passed as `aspect_ratio` to the proxy) to control image proportions. Sending only `size` as pixel dimensions does not map to a native Gemini aspect ratio.

## Fix

### `packages/runner-harness/src/tools/image-generate.ts`
- Added `aspectRatio` property to schema with enum `["1:1", "3:4", "4:3", "9:16", "16:9"]`
- Added 3:4 pixel sizes to `size` enum: `768x1024`, `1024x768`, `960x1280`, `1280x960`
- When `aspectRatio` is provided, sends `aspect_ratio` in the API request body
- Updated `promptSnippet` and `promptGuidelines` to mention `aspectRatio`

### `packages/runner-pi/src/image-tools.ts`
- Same schema additions and API body changes as above

### `packages/runner-pi/src/__tests__/image-tools.test.ts`
- Added test: sends `aspect_ratio` in request body when `aspectRatio` param is provided
- Added test: does NOT send `aspect_ratio` when `aspectRatio` is absent

## Usage

To generate a 3:4 portrait image with `gemini-3-pro-image`, the agent now calls:

```json
{
  "prompt": "a beautiful landscape",
  "filename": "landscape.png",
  "aspectRatio": "3:4"
}
```

This sends `aspect_ratio: "3:4"` to the proxy, which forwards it to the Gemini Image API.

## Follow-up: aspectRatio precedence

After review, the tool now omits the default `size: "1024x1024"` whenever `aspectRatio` is provided. This prevents OpenAI-compatible proxies from prioritizing the square `size` value over Gemini's native `aspect_ratio` parameter. Requests for `aspectRatio: "3:4"` are sent unchanged as `aspect_ratio: "3:4"`.

## Follow-up: supported size values

The `size` schema was corrected to only expose supported values: `auto`, `1024x1024`, `1536x1024`, `1024x1536`, `256x256`, `512x512`, `1792x1024`, and `1024x1792`. Explicit supported `size` values are now preserved even when `aspectRatio` is also provided.

## Follow-up: Gemini-supported aspect ratios

The `aspectRatio` schema was expanded to include the full supported set for Gemini 2.5 Flash Image and Gemini 3 Pro Image: `1:1`, `3:2`, `2:3`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, and `21:9`.

## Follow-up: K-resolution imageSize

Added `imageSize` with `1K`, `2K`, and `4K` values for models that support K-resolution output. The request body now sends top-level `image_size` when provided and no longer adds the default `size: "1024x1024"` when `aspectRatio` or `imageSize` is present.

## Follow-up: release branch CI

Enabled CI for pull requests targeting `release/**` branches so release backports run the same build, typecheck, lint, and test workflow as `main` and `develop` pull requests.

## Follow-up: Gemini edit image parameters

Extended `edit_image` in `packages/runner-pi/src/image-tools.ts` to accept the Gemini image editing controls shown in the Gemini 3 Pro Image examples:

- `aspectRatio` -> multipart `aspect_ratio`
- `imageSize` -> multipart `image_size`

The tool still uses the existing OpenAI-compatible `/v1/images/edits` multipart endpoint, but can now pass the Gemini-specific fields needed by Google Vertex AI / Gemini image edit gateways without adding `response_modalities` or other low-level Gemini request fields. Response parsing also accepts Gemini `inlineData.data` image parts nested under `candidates[].content.parts[]` in addition to OpenAI-style `data[].b64_json` and proxy-specific `imageBase64`.

Added regression tests for Gemini edit control forwarding and Gemini inline image response saving.
