Diagnóstico de imágenes

Cuándo y cómo usarla

Siempre debes usar esta API antes de asociar una imagen a una publicación, durante el proceso de carga de imágenes, tanto para la imagen principal, variantes o imágenes secundarias.

Llamada:

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

  }
}'

Ejemplo:

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"
  }
}'

Campos del body:

Qué es el picture_type y para qué sirve?

Existen tres valores posibles:

• thumbnail: Imagen principal de la publicación. Es la foto más importante, la que primero ve el comprador y la que tiene reglas más estrictas.
• variation_thumbnail: Imagen de una variante del producto (por ejemplo, diferentes colores o tallas). También tiene reglas estrictas, pero pueden variar respecto a la imagen principal.
• other: Imágenes secundarias o adicionales, como fotos de detalles o ángulos diferentes. Tienen reglas más flexibles.

 //Para la imagen principal 
"picture_type": "thumbnail"

//Para una variante
"picture_type": "variation_thumbnail"

//Para una imagen secundaria
"picture_type": "other"

Respuesta

Cuando se realiza un análisis de imagen sin picture_type, la API devuelve una estructura como esta:

{
  "id": "f0b6198b-a4ef-4291-82a5-41956e0af96e",
  "diagnostics": [
    {
      "picture_type": "thumbnail",
      "action": "diagnostic",
      "detections": [
        {
          "name": "text_logo",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "Elimina tus fotos que contienen logos y/o textos."
            }
          ]
        },
        {
          "name": "white_background",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "El fondo de tu foto debe ser blanco digitalizado."
            }
          ]
        }
      ]
    },
    {
      "picture_type": "variation thumbnail",
      "action": "diagnostic",
      "detections": [
        {
          "name": "text_logo",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "Elimina tus fotos que contienen logos y/o textos."
            }
          ]
        },
        {
          "name": "white_background",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "El fondo de tu foto debe ser blanco digitalizado."
            }
          ]
        }
      ]
    },
    {
      "picture_type": "other",
      "action": "empty",
      "detections": []
    }
  ]
}

Campos de respuesta

• id: identificador del diagnóstico
• diagnostics: Listado de detecciones por tipo de imagen.
  • picture_type: Tipo de foto para la cual aplica la detección (thumbnail | variation_thumbnail | other)
  • action: Si es "diagnostic", hay problemas a corregir. Si es "empty", la imagen es válida.
  • detections: Listado de todas las detecciones que fueron encontradas para la foto (si la acción es "empty", se retorna vacío este campo).
    • name: Tipo de problema detectado
    • wordings: Mensajes claros para mostrar al usuario y guiar la corrección.
      • kind: Tipo de wording (siempre REMEDY_SHORT)
      • value: Valor del wording al usuario final.

Buenas prácticas y recomendaciones

• Siempre especifica el picture_type si sabes dónde se usará la imagen. Así vas a obtener diagnósticos precisos y relevantes.
• Valida cada imagen al momento de cargarla, antes de asociarla a la publicación.
• Muestra los mensajes de la API directamente al usuario, para que pueda corregir los problemas antes de publicar.
• No bloquees el flujo si la API falla: permite continuar, pero informa que no se pudo validar la imagen.
• Si recibes diagnósticos para varios tipos de imagen, filtra y muestra solo el que corresponda según el uso real de la imagen.
• Prioriza la validación de la imagen principal (thumbnail), ya que es la más relevante para la publicación.

Siguiente: Moderaciones de Imágenes