Gemini image API: Setting Aspect Ratio and Resolution

If you have already placed a Gemini image API call and ended up with the wrong shape or a soft-looking output, the fix usually lives in one place: the response_format object passed to interactions.create(). Two nested fields, aspect_ratio and image_size, control the rendered image, and setting them explicitly is the difference between a predictable asset and a one-off generation. The behavior below is taken from Google's image-generation documentation, so you can match it against the live page if a token changes.

Where aspect ratio and resolution live in the request

The Gemini image API exposes image-output controls through a single response_format object. Inside that object, aspect_ratio accepts a string such as "16:9" and image_size accepts a token such as "2K". According to ai.google.dev/gemini-api/docs/image-generation, you can control "the aspect ratio and output image size using the aspect_ratio and image_size fields within response_format." If you omit both, the documented default behavior is that the output size automatically matches the input image, or the model falls back to 1:1 squares when there is no input.

The response_format field, briefly

response_format accepts either a single object or an array. Pass a single object when you want only an image back; pass an array when you want text plus image. The shape used in the official Python example for a 2K, 16:9 image is:

response_format = {
    "type": "image",
    "mime_type": "image/jpeg",
    "aspect_ratio": "16:9",
    "image_size": "2K",
}

Setting type to "image" suppresses the conversational text reply and returns the generated image only, which is the cleanest pattern for a generation-only workflow. If you need a caption plus an image, swap the single object for a list like [{"type": "text"}, {"type": "image"}], as shown in the same docs page.

Choosing an aspect_ratio

The only aspect ratio value explicitly shown in the current image-generation documentation is "16:9", used inside response_format for the official landscape infographic example. For prompt-only requests with no response_format supplied, the documented default is 1:1 squares. The docs do not enumerate a wider list of supported aspect ratio tokens on this page, so the safest path is to start from the official example and confirm any additional tokens in the model reference at ai.google.dev/gemini-api/docs/models before using them. Pass the value as a string exactly as it appears in the model reference, not as a number or a colon-free shorthand.

Choosing an image_size

The single image-size token explicitly confirmed in the current image-generation docs is "2K", used together with "16:9" to produce a higher-resolution landscape image in the multi-turn infographic example. Treat this token as the documented high-resolution switch for the Gemini image API; the docs do not enumerate a wider list at the time of writing, so confirm any additional tokens in the model reference at ai.google.dev/gemini-api/docs/models before relying on them.

Defaults and when they kick in

Google's docs state that the output size "automatically matches the size of the input image, or is generated as 1:1 squares." That has two practical consequences:

If you send an edit request with a reference image and you do not pass response_format, the output inherits the reference's resolution and aspect ratio.
If you send a text-to-image request with no image input and no response_format, you get a 1:1 image whose resolution is decided by the model.

For predictable, repeatable results, for example a banner asset or a product card, set both aspect_ratio and image_size explicitly on every call.

Step-by-step Python example

The following Gemini image API example mirrors the official "update an infographic" pattern, condensed to focus on the resolution and aspect ratio fields. It assumes you have the google-genai package installed and a GEMINI_API_KEY available as an environment variable; for a fresh setup, see the Nano Banana quickstart and the how-to-run-locally guide for context on cloud API versus local open-weight models.

import base64
from google import genai

client = genai.Client()  # reads GEMINI_API_KEY from the environment

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input="Update this infographic to be in Spanish. Do not change any other elements of the image.",
    previous_interaction_id="<PREVIOUS_INTERACTION_ID>",
    response_format={
        "type": "image",
        "mime_type": "image/jpeg",
        "aspect_ratio": "16:9",
        "image_size": "2K",
    },
)

if interaction.output_image:
    with open("hero.jpg", "wb") as f:
        f.write(base64.b64decode(interaction.output_image.data))

The bytes returned in interaction.output_image.data are base64-encoded; the helper above decodes and writes them to disk. Confirm the exact field names and supported tokens against the live reference at ai.google.dev/gemini-api/docs/image-generation before shipping, since model field names can shift between releases.

Editing across turns

For multi-turn edits, pass previous_interaction_id instead of re-uploading the image, as shown in the official infographic-to-Spanish example. You can still set response_format on the follow-up call, which is how the official docs convert an English infographic to a 16:9, 2K Spanish version without re-prompting the layout. If a turn returns a ratio or size you did not expect, note that the documentation states that without response_format, the output size automatically matches the input image size or defaults to 1:1 squares; it does not state that it inherits the previous turn's shape in a multi-turn edit. To ensure the desired output, explicitly set response_format on each call.

Quick checklist before you ship

Confirm the model name in the model reference at ai.google.dev/gemini-api/docs/models; gemini-3.1-flash-image is the current generation example in the image-generation docs.
Always pass aspect_ratio and image_size for asset-style output rather than relying on defaults.
Set type: "image" on response_format when you do not want a text reply, or use an array form for text-plus-image.
Remember that every generated image carries a SynthID watermark, per the image-generation documentation.
If something looks off, the Nano Banana FAQ covers environment variable setup and common request shape mistakes.