Mercado Libre poor_quality_thumbnail: fix the cover photo

A listing tagged poor_quality_thumbnail has been moderated for image quality, and it can be active or paused while it carries the tag (Mercado Libre Developers, page last updated 21/07/2025, read 2026-10-03). The fix is a new cover photo, and the moderation record tells you what was wrong with the old one.

Read that record first with the moderations endpoint, then regenerate the cover with Sume to remove the problem the record names. Sume cannot clear the moderation itself, and an edited photo must still show the real product. Both steps run from a script, so a seller with many flagged listings can work through them in one pass, one request per SKU, and compare every result against the supplier photo before anything is uploaded.

How do you read why a listing was moderated?

The page documents GET https://api.mercadolibre.com/moderations/last_moderation/{MODERATION_REFERENCE_ID}, with the reference id taken from its Manage Moderations section. The response is a list. Each entry has a name, wordings with a REASON and a REMEDY, and evidence that names the affected picture ids (read 2026-10-03).

import os, requests

H = {"Authorization": f"Bearer {os.environ['ML_ACCESS_TOKEN']}"}
ref = os.environ["MODERATION_REFERENCE_ID"]
url = f"https://api.mercadolibre.com/moderations/last_moderation/{ref}"
r = requests.get(url, headers=H, timeout=30)
r.raise_for_status()
for m in r.json():
    print(m["name"])
    for w in m.get("wordings", []):
        print(" ", w["type"], "-", w["value"])
    for e in m.get("evidence", []):
        print("  picture:", e["text_matched"])

What do the documented reasons ask you to change?

The page shows two examples. A WATERMARK entry says the cover photo contains watermarks and asks you to remove the photos that contain them. A MULTIPLE entry says some cover photos do not meet the photo requirements, with remedies that name lighting, cropping, watermarks, logos and text (read 2026-10-03). The table maps each to a Sume action.

How do you regenerate a clean cover with Sume?

Use the clean supplier photo as the reference, not the moderated image, so the watermark is never an input. openai/gpt-image-2.5 accepts references and an optional mask_url for edits. If only a corner is marked, a mask over that corner keeps the rest of the picture as it is. If the framing is the problem, regenerate the whole scene and ask for margin around the product.

Ask for what Mercado Libre's remedies describe and nothing more: even light, product fully inside the frame, plain background, no added text. Then compare the result with the source photo. An image model can change a stitch pattern, a label or a port, and a listing photo that differs from the product is a worse problem than a low-quality one.

curl -sS -X POST "https://api.sume.com/v1/images" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ml-sku-1042-cover-v2" \
  -d '{
    "model": "openai/gpt-image-2.5",
    "prompt": "The product centered on a plain white background, evenly lit, a clear margin on every side, no text, no logos added, no watermark",
    "input_references": [{"type": "image_url",
      "image_url": {"url": "https://cdn.example.com/sku-1042-supplier.jpg"}}],
    "image_size": "1200x1200"
  }'

How do you get the new photo onto the listing?

The moderation page recommends running new images through its Image Diagnostics API before upload, and it names three inputs: base64, a picture_id already on the Mercado Libre CDN, or a URL. It also says to upload to the CDN with https://api.mercadolibre.com/pictures/items/upload (read 2026-10-03).

On replacement, the pictures guide adds a rule that bites regenerated covers: use a new source name, or the same source with new content will not update (read 2026-10-03). Name the file with a version suffix and send the new source on the item. The pictures API post walks through the upload and link calls.

What should you check before you resubmit a batch?

If a seller has dozens of paused listings, fetch the moderation record for each and group them by reason, because a mask edit and a full regeneration are different jobs. A watermark sitting in one corner is a cheap, local edit. A product cut off at the edge needs a new composition. Run one listing from each group through the whole loop first: read the record, regenerate, compare with the supplier photo, upload, replace the picture on the item, and look at the listing. Only then queue the rest, with one request per SKU in async mode so a slow generation never blocks the loop.

• Start from the supplier photo, never from a moderated image.
• Do not ask the model for banners, badges or price text on a cover photo. The documented remedies remove text and logos.
• Compare each result with the source for labels, colors and small parts before upload.
• Use a distinct Idempotency-Key per SKU and version. A changed prompt under the same key returns 409.
• Open the listing after the update and confirm the tag has cleared, since only Mercado Libre can clear it.