HEAD-check reference image URLs before an image edit call (Python)

Reference images fail for boring reasons: a URL that needs a login, a 40 MB TIFF, a link that starts with http. The vendors state limits. OpenAI's guide says images and masks used for edits must be under 50 MB, and that the image and its mask must share the same format and size. Ideogram's reference image docs accept JPEG, PNG and WebP up to 25 MB each.

Sume's Image API page adds its own rule: reference URLs must be public HTTPS, and localhost, private-network and non-HTTPS URLs are rejected before submission. A failed download comes back as input_media_unreachable, which is marked not retryable, so fix the input rather than retrying.

The limits side by side

A pre-flight script

Use the strictest limit you will meet, 25 MB, so one check serves every model.

import requests

OK_TYPES = {"image/jpeg", "image/png", "image/webp"}
LIMIT = 25 * 1024 * 1024

def check(url: str) -> str:
    if not url.startswith("https://"):
        return "not https"
    r = requests.head(url, allow_redirects=True, timeout=10)
    if r.status_code != 200:
        return f"status {r.status_code}"
    ctype = r.headers.get("content-type", "").split(";")[0]
    size = int(r.headers.get("content-length", 0))
    if ctype not in OK_TYPES:
        return f"type {ctype}"
    return "too large" if size > LIMIT else "ok"

print(check("https://example.com/photo.jpg"))

Notes

Some hosts answer HEAD with a missing length; treat a 0 size as unknown and fall back to a ranged GET if size matters. This check cannot catch a URL that works for you but not for a server, such as one behind a cookie, so test one real call after a change of host.

How this was checked

Vendor facts come from the pages listed in the sources, read on 2026-10-05. Sume facts come from the Image API docs and the catalog code on main on the same date. Catalogs and limits change, so read the descriptors from GET /v1/images/models before you pin a number in production code.