Diagnóstico de imagens

A API de diagnóstico de imagens permite validar imagens antes de associá-las a uma publicação no Mercado Livre. Seu objetivo é detectar problemas e retornar mensagens claras para que o usuário possa corrigi-los antes de publicar, evitando moderações e melhorando a experiência.

Esta funcionalidade permite:

Obter apenas os problemas atuais de uma imagem.
Diagnosticar antes de associar a imagem à publicação.
Exibir mensagens claras (wordings) para que o seller possa corrigir erros facilmente.

Nota:

Atualmente esta API diagnostica apenas pelos seguintes critérios (conforme a categoria):

Fundos que não são brancos (white_background).
Não cumprimento do tamanho mínimo (minimum_size).
Textos ou logos não permitidos (text_logo).
Marcas d’água (watermark).

Quando e como usar

Você deve sempre usar esta API antes de associar uma imagem a uma publicação, durante o processo de upload de imagens, seja para a imagem principal, variantes ou imagens secundárias.

Chamada:

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_DA_IMAGEM_OU_BASE64_OU_PICTURE_ID",
  "context": {
    "category_id": "ID_CATEGORIA",
    "title": "TITULO_PUBLICACAO", 
    "picture_type": "thumbnail"
  }
}'

Exemplo:

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/minha_imagem.jpg",
  "context": {
    "category_id": "MLA1346",
    "title": "This a item title",
    "picture_type": "thumbnail"
  }
}'

Campos do body:

Atributo	Descrição	Obrigatório	Observação
id	Identificador do diagnóstico	Não	Se não for enviado, será gerado automaticamente.
picture_url	Pode ser uma URL pública, uma string em base64 ou um picture_id do Mercado Livre.	Sim	Qualquer uma das três formas deve ser informada neste campo.
context	Informação contextual adicional	Sim
context.category_id	ID da categoria do item. Define as regras de validação aplicáveis.	Sim	Se a categoria não existir, apenas o minimum_size será avaliado.
context.title	Título da publicação	Não	Recomendado para fornecer mais contexto da publicação.
context.picture_type	Tipo de imagem (thumbnail \| variation_thumbnail \| other). Obrigatório se souber onde a imagem será usada	Não	Indica onde a imagem será usada. Se informado, filtra os resultados; caso contrário, todas as opções são avaliadas.

O que é picture_type e para que serve?

O campo picture_type indica o papel ou o local da imagem dentro da publicação. Ele é fundamental para que a API realize as validações corretas conforme o uso real da imagem.

Existem três valores possíveis:

thumbnail: Imagem principal da publicação. É a mais importante, a primeira que o comprador vê e a que possui regras mais rígidas.
variation_thumbnail: Imagem de uma variação do produto (ex: cores ou tamanhos). Tem regras específicas.
other: Imagens adicionais como ângulos ou detalhes. Possuem regras mais flexíveis.

//Para a imagem principal
"picture_type": "thumbnail"

//Para uma variação
"picture_type": "variation_thumbnail"

//Para uma imagem adicional
"picture_type": "other"

Importante:

Se você souber onde a imagem será usada, SEMPRE especifique o picture_type.
Se não for especificado, a API retornará diagnósticos para os três tipos, e você deverá filtrar e exibir apenas o adequado.

Resposta

Quando você realiza uma análise de imagem sem picture_type, a API retorna uma estrutura como esta:

{
  "id": "f0b6198b-a4ef-4291-82a5-41956e0af96e",
  "diagnostics": [
    {
      "picture_type": "thumbnail",
      "action": "diagnostic",
      "detections": [
        {
          "name": "text_logo",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "Remova suas fotos que contêm logos e/ou textos."
            }
          ]
        },
        {
          "name": "white_background",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "O fundo da sua foto deve ser branco digitalizado."
            }
          ]
        }
      ]
    },
    {
      "picture_type": "variation thumbnail",
      "action": "diagnostic",
      "detections": [
        {
          "name": "text_logo",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "Remova suas fotos que contêm logos e/ou textos."
            }
          ]
        },
        {
          "name": "white_background",
          "wordings": [
            {
              "kind": "REMEDY_SHORT",
              "value": "O fundo da sua foto deve ser branco digitalizado."
            }
          ]
        }
      ]
    },
    {
      "picture_type": "other",
      "action": "empty",
      "detections": []
    }
  ]
}

Campos de resposta

id: identificador do diagnóstico
diagnostics: Lista de detecções por tipo de imagem.
- picture_type: Tipo de imagem (thumbnail | variation_thumbnail | other)
- action: "diagnostic" indica problemas; "empty" indica imagem válida.
- detections: Lista das detecções encontradas.
  - name: Tipo de problema detectado
  - wordings: Mensagens claras para mostrar ao usuário
    - kind: Tipo de wording (sempre REMEDY_SHORT)
    - value: Texto mostrado ao usuário final

Boas práticas e recomendações

Sempre especifique o picture_type se souber onde a imagem será usada.
Valide cada imagem ao carregá-la, antes de associá-la à publicação.
Mostre as mensagens da API diretamente ao usuário, para que ele corrija antes de publicar.
Não bloqueie o fluxo se a API falhar: permita continuar, mas informe que não foi possível validar a imagem.
Se receber diagnósticos para vários tipos, filtre e mostre apenas o correspondente.
Priorize a validação da imagem principal (thumbnail), pois é a mais importante.

Próximo: Moderação de Imagens