Working with pictures

Recommendations for uploading images

- RGB pictures are highly recommended over CMYK pictures.

- The maximum size we accept is 1920 x 1920 px (F version) and the minimum is 40 x 40 px (M version). If the image has higher resolution, it will be resized for version F.

- If the image is smaller than the minimum, it will be the same size (we will not enlarge the image).

- There are um maximum images per item allowed to publish according to the category.

- For pictures wider than 800 pixels, a zoom widget is activated so when buyers roll over they can take a close-up look. This is highly recommended for Clothes.

- You’re allowed to upload pictures up to 10 MB in the following formats:

• JPG
• JPEG
• PNG

Validate and upload pictures

This feature allows you, before uploading an image, perform online validation of the size of the image sent through a smartcrop process, which removes the excess background so that the product has an adequate relationship with the size of the image.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST  \
-H 'content-type: multipart/form-data' \
-F 'file=@FILE' \
https://api.mercadolibre.com/pictures/items/upload

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST  \
-H 'content-type: multipart/form-data' \
-F 'file=@/Users/Documents/test.jpg' \
'https://api.mercadolibre.com/pictures/items/upload'

Valid image response:

{
   "id": "123-MLM456_112021",
   "variations": [
       {
           "size": "1920x1076",
           "url": "http://http2.mlstatic.com/D_NQ_NP_123-MLA456_112021-F.jpg",
           "secure_url": "https://http2.mlstatic.com/D_NQ_NP_123-MLA456_112021-F.jpg"
       },
       {
           "size": "500x280",
           "url": "http://http2.mlstatic.com/D_NQ_NP_123-MLA456_112021-O.jpg",
           "secure_url": "https://http2.mlstatic.com/D_NQ_NP_123-MLA456_112021-O.jpg"
       },
       {
           "size": "400x400",
           "url": "http://http2.mlstatic.com/D_NQ_NP_123-MLA456_112021-C.jpg",
           "secure_url": "https://http2.mlstatic.com/D_NQ_NP_123-MLA456_112021-C.jpg"
       },
[...]
}

We recommend using the obtained id to make a new publication or associate the image with an existing publication.

Invalid image response:

{
   "message": "Asegúrate de que la imagen tenga como mínimo 500 píxeles en uno de los lados. Tené en cuenta que de tener bordes en blanco estos se eliminan dejando un margen total del 10%. Te recomendamos usar 1200 x 1200 para poder hacer zoom. La imagen subida, procesados los bordes blancos, tiene un tamaño de 376px x 340px",
   "error": "bad_request",
   "status": 400,
   "cause": []
}

In the case that the image does not exceed the minimum size, it will return an http 400 error, informing the details of the same.

Link a picture to your Item

Using the picture id obtained before, you can link the picture to your item, like this example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-H "Content-Type: application/json"
-H "Accept: application/json" -d 
{
  "id": "676385-CBT42336685170_062020"
}
https://api.mercadolibre.com/items/$ITEM_ID/pictures

That’s all! Go to your item’s description page (using the permalink field) and check how your picture displays.

Replace pictures in Variations and Global Item

If you need to replace the current pictures of an item, you need to link the pictures to your item and then make a PUT including the Item ID and the picture ID previously linked, with your access_token like in the following example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
'{
  "pictures": [
    {
      "id": "679765-CBT423366854653_082021"
    },
    {
      "id": "4629765-CBT423354837509_042020"
    }
  ]
}
' https://api.mercadolibre.com/global/items/$ITEM_ID

Important

• If you want to replace an image, omit old ID in pictures_id array and be assurance to set new picture ID previously linked.
• In case you have a set of images and you wish to perform the following actions: Add a new image: you should send the IDs of the uploaded images that you wish to keep, along with the ID of the new images previously linked. Besides, you can change the order by sending it in the body of the PUT request as you wish to view them.

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
'{
    "pictures": [
        {
            "id": "679765-CBT423366854653_082021"
        },
        {
            "id": "636579-CBT42348571098_062020"
        },
        {
            "id": "676385-CBT42336685170_062020"
        }
    ],
    "variations": [
        {
            "id": "16787985187",
            "picture_ids": [
                "753377-CBT32543573702_102019",
                "666344-CBT42350430700_062020",
                "679765-CBT423366854653_082021"
            ]
        }
    ]
}' 
http://api.mercadolibre.com/global/items/$ITEM_ID

To delete an image you should only send the IDs of the uploaded images you want to keep.

Check possible errors

If loading the item displays an error message (e.g., "Processing Image ..."), you can check the following:

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/pictures/$PICTURE_ID/errors

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/pictures/622077-CBT42350860502_062020/errors

Response:

{
  "id": "622077-CBT42350860502_062020",
  "source": "https://s3.amazonaws.com/images/pictures/146.111111.jpg",
  "status": "PENDING",
  "error": "{error_code=response_code, meta={responseCode=403, responseMessage=Forbidden, contentType=application/xml, contentLength=-1, contentEncoding=null}}"
}

Image format

• Use the browser to check that the image exists and verify potential errors.
• If the image error continues when uploading an item, you can identify why, using the last call.
• Verify Content-Type against the extension, checking the image with curl -v

curl -v 'image link' >> /dev/null

curl -v 'https://s3.amazonaws.com/images/pictures/146.111111.jpg' >> /dev/null

• Download the image with curl -O "image link" and run the File command to verify the extension.

curl -O "https://s3.amazonaws.com/images/pictures/146.111111.jpg"

file 146.111111.jpg

Obtaining the answer as follows:

146.111111.jpg: XML 1.0 document text, ASCII text

Both should match the formats that we work with: *based on uploading speed.

• JPG
• JPEG
• PNG

Errors

Connection/block 

Check if you are working with Mercado Libre IPs block:

• 216.33.196.4
• 216.33.196.25
• 54.88.218.97
• 18.215.140.160
• 18.213.114.129
• 18.206.34.84

Check if the URL has a redirection. The link should redirect exactly to the image. For example, if the URL is http but changes to https when entered in the browser, it means that there was a redirection.)

If the SSL certificate is incompatible with our server, we recommend getting the SSL by sending the URLs with HTTP.