Check a reference image URL before sending it to Sume Images

Sume requires reference image URLs to be public HTTPS and rejects localhost, private-network and non-HTTPS URLs before it submits the job. A local pre-flight check saves a round trip: confirm the scheme is https and the host is not localhost or a private IP, then send. Sume still performs its own check, so treat yours as a convenience.

The rule

The Image API docs state it in the image-to-image section. They also say that if a model's input_references descriptor is min 0, max 0, the model is text-to-image only and rejects references. So a good pre-flight has two parts: the URL shape and the model capability.

A pre-flight function

This one checks only the URL shape. It does not fetch the URL, so it cannot know whether the file is reachable from the internet.

import ipaddress
from urllib.parse import urlparse


def reference_url_ok(url):
    p = urlparse(url)
    if p.scheme != "https" or not p.hostname:
        return False
    host = p.hostname.lower()
    if host == "localhost" or host.endswith(".local"):
        return False
    try:
        ip = ipaddress.ip_address(host)
    except ValueError:
        return True
    return ip.is_global


if __name__ == "__main__":
    for u in ["https://example.com/a.jpg", "http://example.com/a.jpg", "https://localhost/a.jpg", "https://10.0.0.5/a.jpg"]:
        print(u, reference_url_ok(u))

What it cannot catch

A name that resolves to a private address, a URL that expires, or a file behind a login will pass this check and still fail. Use a stable public URL, such as an object-store link with a long lifetime, and read the error code if Sume rejects it.

• Send the references as input_references with type image_url.
• Check the n and input_references ranges in GET /v1/images/models for the model you picked.
• ChatGPT Image 2.5 takes up to 16 references; ChatGPT Image 2 takes up to 10.