This page is for developers calling image generation/editing models via API. It clears up the two most commonly confused questions: ① What determines the resolution of the output image? ② Does compressing input reference images make the output blurry? The conclusions apply to Nano Banana, GPT image, SeeDream, Flux, and other image models, independent of any specific product UI.
Two Completely Different Things
When calling an image model, there are two “resolutions”. They are two independent fields in the request — don’t mix them up:
| Input image resolution / compression | Output image resolution |
|---|
| What it refers to | The size/pixels of the reference image / image to edit you upload | The size/pixels of the image the model generates |
| What determines it | The compression you apply before uploading | The size parameter in the request (size / imageSize / aspect_ratio) |
| Where it lives in the request | Image data fields (e.g. inline_data.data, image[], input_image) | The size parameter field — completely unrelated to the image data |
Compressing Quality or Compressing Dimensions? What “Compression” Actually Compresses
“Compression” gets used loosely, but an image has two independent kinds of “size”, each with its own compression lever:
| Pixel dimensions (resolution) | File size |
|---|
| What it refers to | Width × height in pixels, e.g. 4284×5712 | Disk/bandwidth footprint, e.g. 4.6 MB |
| What determines it | The resolution at capture/generation time | Pixel count × encoding quality × visual complexity |
| Compression lever | Resizing: shrink the longest edge proportionally — fewer pixels | Re-encoding: lossy JPEG/WebP encoding — same pixels, smaller file |
- A photo from an iPhone 16 Pro measures 4284×5712 (about 24 megapixels — very large) yet the file is only 4.6 MB, because the system already applied efficient lossy encoding when saving;
- A photo with the same pixel count exported at high quality can approach 30 MB.
So “does this image need compressing” can’t be judged by pixels alone or by file size alone — they affect different stages:
- Pixel dimensions set the ceiling on how much information the model can “see”, and the decoding/understanding cost;
- File size drives transfer costs: the ~33% Base64 inflation, upload time, and the 20 MB single-file cap all target bytes.
The practical recommendation is to do both, in order: first cap pixels (shrink the longest edge to ≤ 2048px proportionally), then cap quality (re-encode at 0.9); and use file size as the trigger (only process files above 1.5 MB). That 4.6 MB photo above would get both steps: the 4284px edge shrinks to 2048px, then re-encodes at quality 0.9 — the file typically drops below 1 MB with no effect on how well the model understands it.
Output Resolution Is Set by the Size Parameter, Not the Prompt
This is the most common misconception, so conclusion first:
Writing “4K”, “HD”, “ultra-clear”, or “8K” in the prompt will NOT make the output 4K. The actual output resolution depends only on the size parameter in the request. The prompt controls “what to draw”, not “how big the output is”.
| Model family | Parameter controlling output size | Value format | Example |
|---|
Gemini image series (e.g. gemini-3-pro-image) | imageConfig.imageSize + imageConfig.aspectRatio | Tier string + ratio | imageSize: "4K", aspectRatio: "16:9" |
| GPT image series (gpt-image, etc.) | size | Pixel string WxH | size: "2048x2048" |
| SeeDream series | size | Pixel string / tier | size: "2048x2048" |
| Flux series | aspect_ratio or width + height | Ratio string / pixels | aspect_ratio: "16:9" |
Example: gemini-3-pro-image
It controls output resolution via the imageSize tier — 1K / 2K / 4K (defaults to 1K if omitted) — with aspectRatio controlling the frame ratio:
{
"contents": [ /* prompt text + input images (if any) */ ],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "16:9",
"imageSize": "4K"
}
}
}
imageSize is the field that actually determines output resolution. Each ratio + tier maps to fixed pixel dimensions — e.g. 1:1 at 1K/2K/4K is roughly 1024×1024 / 2048×2048 / 4096×4096, and 16:9 is roughly 1376×768 / 2752×1536 / 5504×3072.
GPT image series uses a size pixel string
{
"model": "gpt-image-...",
"prompt": "...",
"size": "2048x2048"
}
Key point: if you want 4K, set the size parameter to the matching tier/pixels (e.g. imageSize:"4K" or size:"4096x4096") — do NOT write “4K” in the prompt. The prompt and the size parameter are two independent fields in the request; the engine does not parse “4K” out of your prompt to adjust resolution.
A few models (certain adaptive-output types) do not accept a size parameter — the output resolution is decided by the model itself (typically around 1–1.5K). For these models, 4K cannot be forced via parameters, let alone via the prompt. Check each model’s docs/capability statement.
-
The output is re-generated, not an upscale of your image.
The model paints a new image at the size you specified. Output resolution depends only on
imageSize/size, not on how many pixels the input image had. Whether the input is 3000px or compressed to 2000px, if you choose 4K, you get 4K.
-
The input compression field and the output size field are independent.
Compression only changes the volume/pixels of the “image data” field in the request — it never touches the size parameter field. The two are unrelated in the request.
-
The recommended compression is gentle — well above what the model needs to “see” the image.
In practice, compressing the reference image to a longest edge of ~2048px at JPEG quality ~0.9 is more than enough for the model to understand composition, colors, style, and subject details — these models internally downscale input images to a modest resolution before encoding them anyway.
To Be Rigorous: the Edge Case
In image-to-image / fine editing tasks (strictly preserving tiny textures or small text in a specific region of the input), compressing the input too aggressively (e.g. longest edge down to a few hundred pixels, or quality below 0.5) could theoretically lose some detail and indirectly affect how faithfully the edit preserves the original.
But as long as you follow a gentle standard like “longest edge ≤ 2048px, quality ≥ 0.85”, this effect is negligible in real use. The more precise statement:
Reasonable compression (longest edge 2048px, quality 0.9) → no perceptible effect on output sharpness;
only extreme over-compression could cause detail loss in fine-editing scenarios.
If you compress input images before calling, we recommend these gentle standards — saving bandwidth without losing useful information:
| Item | Recommended value | Notes |
|---|
| Compression trigger threshold | Original > 1.5 MB | Small images don’t need compression — send as-is |
| Longest edge cap | 2048 px | Scale proportionally, keep aspect ratio, never upscale small images |
| Compression quality | 0.9 (0–1) | High quality, virtually lossless to the eye |
| Output format | Keep original format (JPG/PNG/WebP) | Don’t force-convert; use PNG/WebP for transparency |
| Total size for multiple images | Keep under ~6 MB | With multiple reference images, adaptively split the per-image budget |
| Single file cap | ≤ 20 MB | Compress oversized files first to avoid upload timeouts/rejections |
per-image target = clamp(total budget ÷ image count, 0.3MB, 1.5MB). More images → smaller per-image share, keeping the total under control; images already within target pass through untouched.
Fault tolerance: compression is a nice-to-have — keep a fallback. If compressing an image fails, fall back to the original and continue; never abort the whole generation request because the compression step failed.
Generated Images Feeding a Downstream Workflow: Process Them Too
Images produced by APIs are often larger than you expect. Take Nano Banana Pro’s 4K tier as an example (empirical values; varies with each channel’s encoding):
| Channel | Typical size per 4K image |
|---|
| AI Studio channel | ~9 MB |
| Vertex channel | ~18 MB |
Downstream use ≠ needing the pristine original. Compress intermediate workflow images to the “model can understand it” standard; if the final deliverable needs 4K, generate 4K only in the last step — iterate at 1K/2K in between for speed and cost.
More Image-Processing Best Practices
Beyond compression, the following are worth handling before upload in API-calling scenarios:
- Bake EXIF orientation into the pixels: phone photos often store their rotation in the EXIF Orientation tag rather than in the pixels. Some processing pipelines ignore the tag, so the model sees a sideways/upside-down image. Apply the rotation to the pixels before upload (most compression libraries do this automatically when re-encoding).
- Strip EXIF privacy metadata before upload: original photos often carry GPS coordinates, device model, and capture time in EXIF. Strip metadata before sending user photos to a third-party API — re-encoding usually does this as a side effect, but mind the order: apply orientation first, then strip.
- Format compatibility: the iPhone’s default HEIC/HEIF format is unsupported by most image APIs — convert to JPEG/PNG first; use PNG/WebP for transparency; animated GIFs typically only have their first frame read.
- Convert color space to sRGB: Apple device photos commonly use Display P3. Pipelines that ignore the color profile will produce color shifts — convert to sRGB before upload.
- Choose the transfer method per scenario: on the input side, Base64 is the most reliable; URL (
fileUri) upload has strict CDN requirements — see the Nano Banana Series Developer Guide for the trade-offs. On the output side, use the Nano Banana OSS Group to receive URLs instead of Base64.
- Pick the output tier you actually need: don’t request 4K unless the deliverable requires it — slower generation, bigger files, higher downstream transfer/processing cost. Iterate at 1K/2K and switch to 4K only for the final render.
- Persist URL outputs promptly: image URLs returned by APIs expire. Transfer them to your own storage as soon as you receive them — never treat a temporary URL as a permanent asset.
Quick Reference
- Output resolution = the size parameter (
imageSize / size / aspect_ratio), not text in the prompt. Want 4K? Set the parameter — don’t write it in the prompt.
gemini-3-pro-image uses imageSize with tiers 1K / 2K / 4K (default 1K); GPT image series uses a size pixel string.- Input compression and output resolution are unrelated — two independent fields in the request.
- Pixel dimensions and file size are two different things: compression = resize first (longest edge 2048px), then re-encode (quality 0.9); use file size as the trigger (only above 1.5MB).
- Reasonable input compression (longest edge 2048px, quality 0.9) does not affect output sharpness; only extreme over-compression could lose detail in fine editing.
- Recommended input compression: only compress above 1.5MB, longest edge ≤2048px, quality 0.9, keep original format, multi-image total ≤6MB, single file ≤20MB, fall back to the original on failure.
- Compress generated images before feeding them into downstream workflows: a Nano Banana Pro 4K image runs ~9–18 MB per image (varies by channel) — sending it back as-is easily hits limits.
- Handle EXIF and format before upload: bake orientation into pixels, strip GPS and other privacy metadata, convert HEIC to JPEG, convert Display P3 to sRGB.
