Gemini Image Upload Limits: File Size, Image Counts, and Multimodal Tokens

Google Gemini developer APIs accept up to 3,600 images per request in Gemini 1.5 and 2.0, with inline payloads limited to 20MB and File API staging supporting up to 2GB per file, tokenized at a fixed cost of 258 tokens per image. While Gemini models provide expansive multimodal context windows spanning one million to two million tokens, developers frequently encounter upload rejections when confusing consumer chat constraints with developer API architecture.

Google Gemini models support a maximum of 3,600 image files per request in developer APIs. Inline image data limits total Gemini API request payload size to 20MB. Beyond these baseline figures, image handling splits across distinct technical layers, each governed by its own validation boundaries:

• Gemini Web App (gemini.google.com): The consumer browser interface limits standard user prompts to 10 files per prompt. Non-video files carry an individual upload cap of 100MB, while video files can reach up to 2GB.
• Gemini API Inline Payloads: When transmitting base64-encoded image strings directly inside the contents or input array of a JSON request, Google's API gateway enforces a strict 20MB ceiling across the entire HTTP request payload.
• Gemini API File API: For larger image datasets or high-resolution graphics, developers upload assets to Google's temporary Files API staging service. The File API accepts individual image assets up to 2GB and provides up to 20GB of ephemeral storage per project.
• Vertex AI Enterprise Ingestion: Enterprises deploying Gemini models on Google Cloud Vertex AI submit images via Google Cloud Storage buckets (gs:// URIs) with support for up to 3,600 images per request. Direct console browser uploads in the Vertex AI studio interface restrict individual files to 7MB.

Understanding these operational boundaries prevents unexpected request failures during inference:

• Gemini Gems File Limit: 10-File Upload Cap and Knowledge Base SolutionsThe Gemini Gems file limit caps custom knowledge bases at 10 reference files and 100 MB per document. While attached...
• Google Gemini PDF Limits: File Sizes, Page Caps, and Parsing FixesThe Gemini PDF limit enforces distinct document ceilings across environments: 100MB and 10 files per prompt in web...
• CSV File Size Limits: AI Assistant Upload Caps, Parsing Ceilings, and FixesCSV file size limits vary from strict row boundaries in spreadsheets to memory and token constraints in AI chat...
• FastAPI Upload File Size Limits: Memory Spooling, Middleware, and Direct StorageFastAPI imposes no native file size limit, but Starlette spools multipart uploads in memory up to `1,048,576 bytes`...
• Notion File Upload Limits: Size Caps by Plan and Large-File WorkaroundsNotion limits individual file uploads to 5MB on the Free plan and provides unlimited file uploads with a 5GB maximum...
• OpenAI Assistant File Limits: Upload Caps, Size Limits, and SolutionsOpenAI assistant file limits balance responsiveness against overhead, restricting direct attachments while capping...

More on this subject: Agent File and Document Workflows (269 guides)

Unlike text tokens generated by byte-pair encoding algorithms, Google Gemini processes visual inputs through a vision transformer that standardizes images into uniform patch representations. Understanding token consumption is critical when submitting batches of images, as image tokens directly consume prompt context capacity.

In Gemini 1.5, Gemini 2.0, and Gemini 3 models, Google standardizes image inputs using a base unit of 258 tokens:

• Base Resolution Floor: Any image where both dimensions are less than or equal to 384 pixels consumes exactly 258 tokens in the model context window.
• High-Resolution Tiling: Images exceeding 384 pixels along either axis are divided into a dynamic grid of 768 x 768 pixel tiles. Each individual tile consumes 258 tokens.

Google calculates the exact number of tiles using the following mathematical sequence:

1. Determine the crop unit size: Compute floor(min(width, height) / 1.5).
2. Calculate dimension tiles: Divide both image width and height by the computed crop unit size.
3. Compute total tiles: Multiply the horizontal and vertical tile counts together.
4. Calculate final image tokens: Multiply the total tile count by 258 tokens.

Consider an engineering team submitting a standard landscape photograph with dimensions of 960 x 540 pixels. The minimum dimension is 540 pixels. Dividing 540 by 1.5 yields a crop unit size of 360 pixels. Dividing width (960 / 360 = 2.66) and rounding up gives 3 horizontal tiles. Dividing height (540 / 360 = 1.5) gives 2 vertical tiles. The image divides into 3 * 2 = 6 tiles, consuming 1,548 tokens (6 * 258).

In Gemini 3 models, Google introduced the media_resolution parameter, providing explicit programmatic control over multimodal token allocation. Setting media_resolution="low" restricts the vision encoder to a single 258-token representation regardless of input pixel dimensions. This optimization lowers latency and reduces token consumption for high-throughput image classification tasks where fine text reading is unnecessary.

When building applications on the Gemini API, developers must choose between passing images inline as base64-encoded strings or uploading files to Google's temporary Files API staging service. Selecting the wrong pipeline causes immediate transport errors or unnecessary network latency.

Inline data passing embeds binary image data directly into the JSON request body using the inline_data field. While convenient for single-turn scripts, base64 encoding substantially inflates raw binary file size. A 16MB JPEG image on disk expands to more than 21MB of base64 text characters when serialized into JSON. This exceeds Google's 20MB inline request ceiling and triggers an immediate HTTP 413 Request Entity Too Large error from the API gateway.

The Google File API (client.files.upload) solves payload bloat by decoupling file transport from model inference. When using the File API:

1. The application transmits the raw binary file to Google's staging endpoint.
2. The File API stores the image in an ephemeral cloud buffer and returns an active file.uri.
3. The application passes the lightweight file.uri inside the contents parameter of client.models.generate_content.
4. The inference engine pulls the image directly from the internal staging buffer during execution.

Files uploaded to the File API are retained for 48 hours before automated deletion. The File API is entirely free of separate storage fees, but project storage is capped at a 20GB staging ceiling across all active assets. File API uploads are write-only staging buffers: client applications cannot download original files back from the API, meaning primary storage must remain in dedicated workspaces.

import os
from google import genai
from google.genai.errors import APIError

def analyze_image_batch(image_paths: list[str], prompt_text: str) -> str:
    client = genai.Client()
    staged_files = []
    try:
        for path in image_paths:
            file_size_mb = os.path.getsize(path) / (1024 * 1024)
            if file_size_mb > 2000.0:
                raise ValueError(f"File {path} exceeds staging threshold.")
            print(f"Staging {path} ({file_size_mb:.2f} MB)...")
            staged_file = client.files.upload(
                file=path,
                config={"mime_type": "image/jpeg"}
            )
            staged_files.append(staged_file)
        request_contents = [prompt_text] + staged_files
        response = client.models.generate_content(
            model="gemini-2.0-flash",
            contents=request_contents
        )
        return response.text
    except APIError as exc:
        if exc.code == 413:
            print("Payload exceeded inline boundaries. Route through Files API.")
        elif exc.code == 400:
            print(f"Ingestion rejected by Gemini API: {exc.message}")
        raise
    finally:
        for staged_file in staged_files:
            try:
                client.files.delete(name=staged_file.name)
            except Exception:
                pass

Production vision pipelines encounter several recurring failure modes when processing diverse visual inputs. Understanding how Gemini handles metadata, orientation, and resolution prevents silent extraction degradation and runtime API crashes.

The most frequent image ingestion failure modes include:

• EXIF Orientation Flags Ignored: Smartphone cameras record physical orientation inside EXIF metadata tags rather than rotating the underlying pixel matrix. While web browsers automatically read EXIF tags and display photos right-side up, vision transformers process raw raster arrays. When an image with an unapplied rotation tag enters Gemini, the model receives sideways or upside-down pixels, causing severe optical character recognition degradation and inaccurate spatial reasoning.
• Extreme Aspect Ratio Truncation: Architectural floor plans, panoramic photos, and full-page mobile screenshots with aspect ratios exceeding 16:1 trigger aggressive downscaling. During tiling, Google's scaling pipeline compresses narrow dimensions, rendering small typography and line annotations unreadable.
• Ephemeral File Expiration in Long Conversations: Multi-turn agent conversations that reference a file.uri over multiple days break when Google's 48-hour File API retention window expires. Once expired, subsequent prompts referencing that URI fail with an HTTP 404 File Not Found error.
• Color Space Conversion Defects: Images encoded in non-standard CMYK print color profiles or 16-bit uncompressed RAW formats trigger decoding errors in Google's vision parser. Images should always be converted to standard sRGB 8-bit color spaces before transmission.

import os
from PIL import Image, ImageOps

def preprocess_image_for_gemini(source_path: str, target_path: str, max_dimension: int = 2048) -> str:
    with Image.open(source_path) as img:
        img = ImageOps.exif_transpose(img)
        if img.mode in ("RGBA", "P"):
            img = img.convert("RGB")
        elif img.mode == "CMYK":
            img = img.convert("RGB")
        width, height = img.size
        if max(width, height) > max_dimension:
            scale_ratio = max_dimension / max(width, height)
            new_size = (int(width * scale_ratio), int(height * scale_ratio))
            img = img.resize(new_size, Image.Resampling.LANCZOS)
            print(f"Rescaled from {width}x{height} to {new_size[0]}x{new_size[1]}")
        img.save(target_path, format="JPEG", quality=88, optimize=True)
    file_size_mb = os.path.getsize(target_path) / (1024 * 1024)
    print(f"Preprocessed image saved: {target_path} ({file_size_mb:.2f} MB)")
    return target_path

preprocess_image_for_gemini("mobile_photo.heic", "normalized_photo.jpg")

Manage Large Image Datasets Without Prompt Upload Limits

Connect your multimodal agents to indexed image libraries via the Fast.io MCP server instead of hitting context and payload ceilings. Starts with a 30-day free trial.

Start 30-Day Trial

When engineering teams move beyond simple single-image prompts to autonomous multi-agent pipelines, attaching hundreds of raw image files directly to model prompts quickly becomes unsustainable. Passing large volumes of image binaries directly into an LLM context window exhausts token limits, increases network latency, and multiplies recurring API costs.

Engineering teams typically evaluate conventional storage options before discovering their operational limitations:

• Local File Storage: Storing images on local server disks works for local evaluation scripts, but isolates files on a single machine. Other agents and human teammates cannot access the files, and version history is absent.
• Raw Cloud Object Storage (Amazon S3 or Google Cloud Storage): Object storage handles petabyte-scale image libraries, but functions as passive bit storage. S3 provides no semantic search, no visual indexing, and no structured querying. Teams must build and maintain custom embedding pipelines, vector databases, and retrieval servers.
• Google Drive Folders: Common for human desktop sharing, but Drive's API rate limits, complex authentication, and background sync timeouts create friction for automated agent loops.

Fast.io provides an intelligent workspace platform built specifically for agentic teams collaborating on complex file collections. Instead of repeatedly stuffing raw image files into model prompts, teams store visual assets in shared, organization-owned workspaces in Fast.io workspaces for AI agents.

Files can be uploaded directly or imported from existing repositories. Fast.io supports cloud sync for Dropbox, Box, and OneDrive; Google Drive imports today, with sync coming soon. Once files arrive in a workspace, enabling Intelligence Mode automatically indexes documents and visual assets for hybrid search, combining exact full-text matching, semantic meaning-based search, and metadata value filtering.

For workflows requiring structured data extraction from visual documents, receipts, and photos, Fast.io provides Metadata Views. Metadata Views turn unstructured file collections into queryable, typed database tables without requiring manual OCR template configuration. Autonomous agents can create views, trigger extraction, and filter extracted attributes directly over MCP.

AI assistants connecting through the remote Fast.io Model Context Protocol (MCP) server at https://mcp.fast.io/mcp/tools query the workspace intelligence layer directly. When an assistant needs information from a multi-thousand-image catalog, it retrieves only the relevant assets or extracted attributes, completely bypassing vendor prompt upload ceilings and recurring visual token overhead.

Every organization starts with a 30-day free trial, which requires a credit card. Subscriptions are available on the Starter plan at $29/mo, Business at $99/mo, and Enterprise at $299/mo on Fast.io pricing, providing team workspaces with version history and a detailed activity log for human-agent collaboration.