Image diagnostics

The Image Diagnostics API allows you to validate images before associating them with a Mercado Libre listing. Its goal is to detect issues and return clear messages so the user can fix them before publishing, avoiding moderations and improving the experience.

This feature allows you to:

Get only the current issues of an image.
Diagnose before associating the image to the listing.
Display clear messages (wordings) so the seller can easily fix errors.

Note:

Currently, this API only diagnoses by the following criteria (as applicable by category):

Non-white backgrounds (white_background).
Failure to meet minimum size (minimum_size).
Unauthorized texts or logos (text_logo).
Watermarks (watermark).

When and how to use it

You should always use this API before associating an image to a listing, during the image upload process, for the main image, variants, or secondary images.

Call:

curl -L -X POST 'https://api.mercadolibre.com/moderations/pictures/diagnostic' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
  "picture_url": "IMAGE_URL_OR_BASE64_OR_PICTURE_ID",
  "context": {
    "category_id": "CATEGORY_ID",
    "title": "LISTING_TITLE", 
    "picture_type": "thumbnail"

  }
}'

Example:

curl -L -X POST 'https://api.mercadolibre.com/moderations/pictures/diagnostic' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer $ACCESS_TOKEN' \
--d '{
  "id": "f0b6198b-a4ef-4291-82a5-41956e0af96e",
  "picture_url": "https://miurl.com/mi_imagen.jpg",
  "context": {
    "category_id": "MLA1346",
    "title": "This a item title",
    "picture_type": "thumbnail"
  }
}'

Body fields:

Attribute	Description	Required	Observation
id	Diagnostics identifier	No	If not sent, it is generated automatically.
picture_url	It can be a public URL or a base64 string.	Yes	formats: URL: https://{{picture}} Base64: data:[][;base64],< data>
picture_id	ID generated for existing photos in Meli's CDN	Yes	E.g.: 123456-MLAXXXXX_782025
context	Additional contextual information	Yes
context.category_id	Item category ID. Defines the applicable validation rules.	Yes	The criteria to be evaluated are chosen depending on the category where you want to use the photo. If the sent category does not exist, only minimum_size will be evaluated
context.title	Listing title	No	Recommended for more context of the listing
context.picture_type	Image type (thumbnail \| variation_thumbnail \| other). Required if you know where the image will be used	No	Indicates where the photo will be used within the item. If provided, it filters the result; if not, all are evaluated.

Note:

When uploading images, the field you must use in the request body depends on the type of data you are going to send:

If you are going to send the ID of an existing image in the CDN, use the picture_id field.
If you are going to send a URL or the image in base64, use the picture_url field.

Remember: you should always send only one of these fields per image.

Valid URLs

When sending an image in the picture_url field, keep in mind that the URL must be public, static, and accessible. Mercado Libre does not handle obtaining or accessing images hosted on external platforms without the correct permissions; the integrator is responsible for providing a valid URL so that our API can process it correctly.

What is picture_type and what is it for?

The picture_type field indicates the role or place the image will occupy within the listing. It is essential for the API to perform the correct validations according to the actual use of the image.

There are three possible values:

thumbnail: Main image of the listing. This is the most important photo, the first one the buyer sees, and it has the strictest rules.
variation_thumbnail: Image of a product variant (for example, different colors or sizes). Also has strict rules, but they may vary from the main image.
other: Secondary or additional images, such as detail or different angle photos. These have more flexible rules.

 //For the main image 
"picture_type": "thumbnail"

//For a variant
"picture_type": "variation_thumbnail"

//For a secondary image
"picture_type": "other"

Important:

If you know where the image will be used, ALWAYS specify picture_type.
If you do not specify it, the API will return diagnostics for all three types, but you must filter and display only the one that corresponds to the actual use of the image.

Response

When an image analysis is performed without picture_type, the API returns a structure like this:

{
  "id": "f0b6198b-a4ef-4291-82a5-41956e0af96e",
  "diagnostics": [
    {
      "picture_type": "thumbnail",
      "action": "diagnostic",
      "detections": [
        {
          "name": "text_logo",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "Remove your photos that contain logos and/or texts."
            }
          ]
        },
        {
          "name": "white_background",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "The background of your photo must be digitized white."
            }
          ]
        }
      ]
    },
    {
      "picture_type": "variation thumbnail",
      "action": "diagnostic",
      "detections": [
        {
          "name": "text_logo",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "Remove your photos that contain logos and/or texts."
            }
          ]
        },
        {
          "name": "white_background",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "The background of your photo must be digitized white."
            }
          ]
        }
      ]
    },
    {
      "picture_type": "other",
      "action": "empty",
      "detections": []
    }
  ]
}

Response fields

id: diagnostics identifier
diagnostics: List of detections by image type.
- picture_type: Type of photo for which the detection applies (thumbnail | variation_thumbnail | other)
- action: If "diagnostic", there are issues to fix. If "empty", the image is valid.
- detections: List of all detections found for the photo (if the action is "empty", this field is returned empty).
  - name: Type of detected issue
  - wordings: Clear messages to display to the user and guide correction.
    - kind: Type of wording (always REMEDY_SHORT)
    - value: Value of the wording for the end user.

Best practices and recommendations

Always specify picture_type if you know where the image will be used. This way, you'll get accurate and relevant diagnostics.
Validate each image at the moment of upload, before associating it to the listing.
Display API messages directly to the user, so they can fix problems before publishing.
Don't block the flow if the API fails: allow to continue, but inform that the image could not be validated.
If you receive diagnostics for several image types, filter and show only the one that corresponds to the real use of the image.
Prioritize validating the main image (thumbnail), as it's the most relevant for the listing.

Next: Image Moderations