The Limit Rose to 128MB, but 176 Images at 17.5MB Still Stop: Count the Wall That Hits Before Bytes

A gate that checks all four

This is the script that produced the output above. It reads image dimensions only, with no decoding, so 176 files finish instantly. It needs Pillow (pip install pillow).

#!/usr/bin/env python3
"""image_gate.py: check an image set against four limits before sending.
  1) count  2) base64 size per image  3) long edge <= 3,000px above 20 images  4) whole request (per route)
Usage: python3 image_gate.py <dir> [--route first-party|bedrock|gcp-google|aws-foundry]
Exit codes: 0=ok / 1=over a limit / 2=no images
"""
import sys, math, pathlib
from PIL import Image
 
MB = 1024 * 1024
ROUTES = {"first-party": 128, "bedrock": 20, "gcp-google": 30, "aws-foundry": 32}
PER_IMAGE_B64 = {"first-party": 10, "bedrock": 5, "gcp-google": 10, "aws-foundry": 10}  # aws-foundry per-image limit unverified: placeholder
MAX_IMAGES = 100          # models with a 200k context window; other models allow 600
MANY_IMAGES, MANY_EDGE = 20, 3000
B64 = lambda n: 4 * math.ceil(n / 3)
EXTS = {".png", ".jpg", ".jpeg", ".webp", ".gif"}
 
def main():
    root = pathlib.Path(sys.argv[1])
    route = sys.argv[sys.argv.index("--route") + 1] if "--route" in sys.argv else "first-party"
    files = sorted(p for p in root.rglob("*") if p.suffix.lower() in EXTS and p.is_file())
    if not files:
        print("no images"); sys.exit(2)
    total = 0; over_one = []; over_edge = []; edges = []
    for p in files:
        b = B64(p.stat().st_size); total += b + 87      # 87 = JSON envelope of one content block
        if b > PER_IMAGE_B64[route] * MB: over_one.append(p.name)
        with Image.open(p) as im: w, h = im.size        # reads the header only
        edges.append(max(w, h))
        if max(w, h) > MANY_EDGE: over_edge.append((p.name, max(w, h)))
    bad = 0
    print(f"route={route} files={len(files)} wire={total/MB:.2f}MB / {ROUTES[route]}MB  max_edge={max(edges)}px  >3000px={len(over_edge)}")
    if len(files) > MAX_IMAGES: print(f"NG count {len(files)} > {MAX_IMAGES}"); bad += 1
    if over_one: print(f"NG single image over limit: {over_one[:3]}"); bad += 1
    if len(files) > MANY_IMAGES and over_edge:
        print(f"NG above 20 images, {len(over_edge)} over 3,000px (e.g. {over_edge[:2]})"); bad += 1
    if total > ROUTES[route] * MB * 0.9: print("NG request above 90% of the route limit"); bad += 1
    print("OK" if not bad else f"NG {bad} issue(s)")
    sys.exit(1 if bad else 0)
 
main()

Three design choices are worth explaining.

• Per-route constants live in dictionaries. Swapping 128MB for Bedrock's 20MB reuses the same check on another route. I wrote about holding constants per route in the piece on Bedrock staying at 20MB.
• The 3,000px check only applies above 20 images. With 19 images, a 6,000px image passes. A rule that changes with the count is easy to miss when you only skim the table.
• Three exit codes keep "no images found" separate from "over the limit", so a nightly job or CI step cannot confuse them.

When it fails, chunk in order

On NG, I split rather than give up. This function bundles images in order while watching both count and bytes.

import math, pathlib
 
MB = 1024 * 1024
B64 = lambda n: 4 * math.ceil(n / 3)
 
def chunk_images(paths, max_count=100, max_wire_mb=115.0, overhead=87):
    """Bundle in order so that both count and bytes stay within limits."""
    chunks, cur, cur_bytes = [], [], 0
    for p in paths:
        w = B64(pathlib.Path(p).stat().st_size) + overhead
        if cur and (len(cur) >= max_count or cur_bytes + w > max_wire_mb * MB):
            chunks.append(cur); cur, cur_bytes = [], 0
        cur.append(p); cur_bytes += w
    if cur: chunks.append(cur)
    return chunks

Running it on the same 176 images:

{}                          -> 2 chunks  [100, 76]
{'max_count': 20}           -> 9 chunks  [20, 20, 20, 20, 20, 20, 20, 20, 16]
{'max_wire_mb': 16.2}       -> 2 chunks  [100, 76]   # 90% of 18MB as the byte cap

Look at lines two and three. Lowering the byte cap for Bedrock's 20MB still gave two chunks. The images are small, so the 100-image count is what binds. With several-MB photos the bytes would bind first. Which wall comes first depends on the bundle.

Putting it into a routine

Here is the order I wired it into my own image-sending step. My recommendation is to put the gate in front of the send, and only go to chunking on NG.

1. Gather the images into one folder (or list) and run image_gate.py.
2. On exit code 0, send them as one request.
3. On exit code 1, read the NG line. For count, pick max_count; for bytes, pick max_wire_mb, then bundle with chunk_images.
4. If a bundle above 20 images has anything over 3,000px, shrink the long edge before bundling (keep re-encoding as a separate step).
5. When you change routes, change only --route and repeat the same steps.

The NG line always says which limit was exceeded, because each one needs a different fix: count means split, long edge means resize, and per-image bytes means compress.

Pitfalls

• The image cap depends on the model. 100 for a 200k context window, 600 otherwise. When you switch models, update MAX_IMAGES too.
• The rules change between 20 and 21 images. Adding a 21st image applies the 3,000px limit to every image. You can also chunk at 20 (the second config above).
• I found no source for the per-image limit on aws-foundry. It is a placeholder, as the code comment says. Check your own route's documentation before relying on it.
• The base64 estimate excludes the rest of the request. If your prompt or other content blocks are large, raise overhead or lower the 90% safe zone.
• For huge PDFs or images you reuse, the Files API lets you reference a file instead of embedding it. I compare the options in the Files API article.

What to do next

Run image_gate.py on your own image folder first. I felt reassured by the byte headroom, and the count failure surprised me. When a limit goes up, do not look at the new number; check which number your own bundle hits first. That is what I took from this.

For pre-send size estimation in general, see designing around 413 request too large. Once you decide how to split a bundle, the next time a limit moves you only edit one constant.