Adobe Commerce product image sizes: base, small, thumbnail

Adobe Commerce does not want one image per size. You upload a base image, assign it roles, and the store serves it as Base, Small, Thumbnail or Swatch. Adobe's documentation (last updated May 14, 2026, read 2026-10-03) gives example sizes of 1100 x 1100 pixels for a base image with zoom, 470 x 470 for listings and 50 x 50 for thumbnails and swatches.

So the job for an AI image pipeline is one large, clean base image per product. Sume can make that. It cannot make the 50-pixel versions, and this post says where that line sits, what Adobe can do for you on upload, and which checks to run on a generated file before it reaches a live product page.

What does each Adobe Commerce image role do?

By default every role is assigned to the first image you upload, and you reassign a role by picking it in the image's detail view (read 2026-10-03). The sizes in the table are Adobe's examples. Your theme's container decides the real numbers.

What size should you ask Sume for?

Adobe says that for zoom the base image should be two or three times the size of its container (read 2026-10-03). For a 470-pixel container that is roughly 940 to 1,410 pixels. On the Sume Image API, openai/gpt-image-2.5 takes custom pixels through image_size: both edges must be multiples of 16, the longest edge at most 3840, and the total between 655,360 and 8,294,400 pixels. 1408 x 1408 meets that and sits near three times 470.

Pass the supplier photo as input_references so the product is reproduced from the real item, and keep the prompt about the background and light, not the product's design. Check the result against the source photo before it goes to a live store.

import os, requests

H = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}",
     "Idempotency-Key": "sku-1042-base-v1"}
body = {
    "model": "openai/gpt-image-2.5",
    "prompt": "The product on a seamless light grey background, even studio light, product fills 90 percent of the frame",
    "input_references": [{"type": "image_url",
                          "image_url": {"url": "https://cdn.example.com/sku-1042.jpg"}}],
    "image_size": "1408x1408",
}
r = requests.post("https://api.sume.com/v1/images", headers=H, json=body, timeout=60)
if r.status_code == 200:
    url = r.json()["data"][0]["url"]
    open("sku-1042-base.png", "wb").write(requests.get(url, timeout=60).content)
elif r.status_code == 202:
    print("still running, poll", r.json()["data"]["status_url"])
else:
    print(r.status_code, r.text)

Why not generate the 470 and 50 pixel versions too?

Because the custom-size box has a floor. Anything under 655,360 pixels, about 810 x 810, is refused for custom sizes, and the Sume docs say exact output pixels are not a feature you can lean on: target_pixels is never applied. A 470 x 470 or 50 x 50 request is therefore not available from the Image API.

Adobe gives you the other half. Its page describes an option to enable automatic resizing of larger files as you upload them, with a maximum pixel size you set (read 2026-10-03). Use that, or resize in your own pipeline after download, and keep Sume for the large master.

How do you run it across a catalog?

Send one request per SKU in async mode (mode: "async"), keep each job id, and fetch results from the standard job endpoints. Sume accepts valid jobs beyond your plan's processing limit as queued work and returns 429 queue_full only when the queue is also full, so a catalog loop waits and retries instead of failing (generation admission, Sume docs).

Give every SKU its own Idempotency-Key. A retried submit with the same key and body is an exact retry, and a changed body under the same key is a 409, which tells you a prompt edit needs a new version suffix. Spot-check one image per product family against the supplier photo before you accept the batch.

What else does Adobe check at upload?

Adobe recommends the sRGB color profile for best compatibility and says other profiles are converted during upload, which could shift color (read 2026-10-03). It also caps file names, including the extension, at 90 characters, and offers a batch import for large catalogs in place of one-by-one uploads.

• Name files with the SKU and a short role hint, and stay under 90 characters including the extension.
• Check the color profile of every generated file before upload, because a conversion can change how a brand color looks.
• Write alt text per image. Adobe says screen readers and search engines read it.
• Use Hide from Product Page for working images you want to keep on the product but not show.
• For many SKUs, submit with a distinct Idempotency-Key each and read the status code: 200 is the image, 202 is a job to poll.