Gemini's GA Image Models Won't Output Exact Device Resolutions — A Wallpaper Pipeline That Fixes Aspect Ratio and Safe Areas

Generating the master with a GA image model

First, generate the master. Migrating off the preview model starts, at its core, with swapping the model ID. Because the GA models may update response field names or supported aspect ratios, always confirm against the changelog before pushing to production.

from google import genai
from google.genai import types
 
client = genai.Client(api_key="YOUR_GEMINI_API_KEY")
 
# The preview models shut down on 6/25. Switch to the GA model ID.
MODEL = "gemini-3.1-pro-image"  # was: gemini-3-pro-image-preview
 
prompt = (
    "A serene minimalist mountain range at dawn, soft gradient sky, "
    "centered composition, generous empty space at top and bottom, "
    "no text, no watermark, high detail"
)
 
resp = client.models.generate_content(
    model=MODEL,
    contents=prompt,
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        # Generate at 9:16 (wider than the device's 0.46) and trim width later
        image_config=types.ImageConfig(aspect_ratio="9:16"),
    ),
)
 
# The generated image comes back in inline_data
for part in resp.candidates[0].content.parts:
    if part.inline_data:
        with open("master.png", "wb") as f:
            f.write(part.inline_data.data)
        break

I put generous empty space at top and bottom in the prompt so the subject survives later cropping. Whether or not that single line is present made a clear difference to my yield at scale.

Fitting to exact device resolution with fit_to_device

Once the master exists, bring it down to each device resolution precisely. The key is the "cover" approach: to avoid letterboxing, scale up until the target is fully covered, then crop from the center.

from PIL import Image
 
def fit_to_device(src_path: str, target_w: int, target_h: int, out_path: str) -> str:
    img = Image.open(src_path).convert("RGB")
    sw, sh = img.size
 
    # cover scale: pick the smallest factor that covers both dimensions (max is the trick)
    scale = max(target_w / sw, target_h / sh)
    nw, nh = round(sw * scale), round(sh * scale)
    img = img.resize((nw, nh), Image.LANCZOS)  # LANCZOS keeps downscaling clean
 
    # center crop to the target resolution
    left = (nw - target_w) // 2
    top = (nh - target_h) // 2
    img = img.crop((left, top, left + target_w, top + target_h))
 
    img.save(out_path, "PNG")
    return out_path

Using max() is the point. With min() the whole image fits but you get empty borders (the "contain" approach). Wallpapers can't have borders, so you cover first and trim the excess with max().

There's one more prerequisite: generate the master larger than every device. If scale exceeds 1 (upscaling is needed), enlargement makes it blurry. To reliably cover the largest 1440×3200, I aim for a 9:16 master with a long edge of at least 3,000px. That keeps the scale at or below 1 for every device, so it's always a downscale.

Writing out every device at once

After that, you just loop over a device table. Generation happens once; cropping happens per device.

DEVICES = {
    "iphone-air":      (1260, 2736),
    "iphone-17-pro":   (1206, 2622),
    "iphone-pro-max":  (1320, 2868),
    "pixel-9-pro":     (1280, 2856),
    "android-xxxhdpi": (1440, 3200),
}
 
import os
os.makedirs("out", exist_ok=True)
for name, (w, h) in DEVICES.items():
    path = fit_to_device("master.png", w, h, f"out/{name}.png")
    print(f"{name}: {w}x{h} -> {path}")
 
# Expected output:
# iphone-air: 1260x2736 -> out/iphone-air.png
# iphone-17-pro: 1206x2622 -> out/iphone-17-pro.png
# ...

With this structure, when a new device ships you add one line to DEVICES. You never touch the generation API.

Keeping the subject from getting clipped via safe areas

Once you crop, the edges are always trimmed. The real question is whether you control which edges get cut. I treat the central 80% as the subject's safe area, and I steer the prompt so the subject avoids the top and bottom where the lock-screen clock and widgets sit.

Checking whether output respects the safe area is faster by overlay than by eye. Keeping a small verification overlay handy makes pre-production checks much easier.

from PIL import Image, ImageDraw
 
def draw_safe_area(path: str, out_path: str, safe: float = 0.8) -> None:
    img = Image.open(path).convert("RGB")
    w, h = img.size
    draw = ImageDraw.Draw(img)
    mx, my = w * (1 - safe) / 2, h * (1 - safe) / 2
    # Draw the central 80% box in red; confirm the subject sits inside it
    draw.rectangle([mx, my, w - mx, h - my], outline=(255, 0, 0), width=6)
    img.save(out_path, "PNG")
 
draw_safe_area("out/iphone-pro-max.png", "check/iphone-pro-max.png")

If the subject spills outside that box, strengthen centered composition in the prompt, or regenerate the master.

What I actually verified migrating from preview to GA

Heading into the 6/25 shutdown, here's the order I checked things against my own pipeline:

1. Swap the model ID from preview to GA (gemini-3.1-pro-image, etc.)
2. Generate just one image and confirm the inline_data extraction hasn't changed
3. Verify the aspect_ratio value I was passing still works on GA
4. Add a fallback path to the most recent master when generation fails

I keep step 4 because API-dependent automation hurts when it stalls during an outage. Even if generation goes down, I can reuse the previous master and still finish that day's export. For the migration steps themselves, see the migration guide to the GA image models; for improving reproducibility of generation, see how to reproduce generations with the seed parameter.

flash or pro — which image model to build with

Which GA model I use for the master depends on the use case. For me, simple gradient or abstract-pattern wallpapers are fine on gemini-3.1-flash-image — cheap, fast, and the throughput matters at scale. For detailed landscapes or pieces where texture is the star, I reach for gemini-3.1-pro-image, because even with the same prompt, the detail that survives after downscaling to device resolution is noticeably better.

The rule of thumb is simple: "does the detail collapse when downscaled to a 3,000px long edge?" Send only the subjects that collapse to pro and run everything else on flash, and the cost/quality balance gets much easier to manage. Building everything on pro looks great but sends your bill soaring.

A word on output format too. I receive PNG right after generation for post-processing, but the final files I bundle into the app are converted to WebP. For the same visual result the file size drops by roughly 30%, which helps app size and download time. For wallpapers, where losslessness isn't required, WebP around quality 90 turned out to be the practical sweet spot.

Five pitfalls that trip people up

Here are the spots where I got stuck, or where I've been asked for help.

1. Specifying a pixel count in the prompt. Writing "make it 1206×2622px" gets ignored; the model returns its fixed aspect ratio. Accept that sizing is the post-processing layer's job.
2. Generating small and upscaling to device resolution. It will always blur. Generate the master larger than every device and only ever downscale.
3. Cropping without considering the safe area. Unless the subject is centered, the edges get clipped. Make margins and centering explicit in the prompt.
4. Generating per device and paying 4x the cost. Crop from one master and generation happens once — a fraction of the device count.
5. Forgetting Android density buckets. I avoid the "resources drop out on low-density devices" failure by placing one high-resolution copy in drawable-nodpi/. For real photographic assets like wallpapers, consolidating into nodpi rather than splitting by density is the safe move.

When shipping the same artwork to both the App Store and Google Play, just keeping these five in mind cut my rejections noticeably. Being able to deliver a piece I made as an artist across every device without breakage is unglamorous, but it pays off in daily operations.

Your next step

Start by running fit_to_device on a single image you have on hand, then use draw_safe_area to overlay the box across every device size and check whether the subject is clipped. Once that's stable, the rest is just raising the quality of your generation prompts to take it to scale. Thank you for reading.