Working with pictures

When list an item, depending on the type of list, the images can be mandatory and make a big difference with respect to quality, that is, they will attract more visits and improve the chances of selling. When you list a new article, you can add images at that time. In this guide, you can see how to upload images to our servers and add them to your articles. Read more about the importance of images. Photos are your window!

Contents

→Considerations & Best Practices
  ↳Zooming
→Validate and upload pictures
→Link a picture to your Item
→Replace pictures
→Check possible errors
  ↳Image format
→HTTP response code references
→What are the sizes and versions available in the images
→Connection/block
→Pictures moderations

Considerations & Best Practices

RGB pictures are highly recommended over CMYK pictures. There is um maximum imagens per item allowed to publish according to the category. You’re allowed to upload pictures up to 10 MB in the following formats:

  • JPG

  • JPEG

  • PNG


Zooming

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 and Real Estate properties. Upload a picture Now is the time to upload your first image file to be stored on our servers. This is really easy to do, just take note of the exact path where you have your image saved:

curl -F file=@/home/user/picture.jpg

https://api.mercadolibre.com/pictures?access_token=$ACCESS_TOKEN

As a response you’ll get a JSON describing the picture details. Remember to keep the picture id. The other fields represent different picture sizes.

{
   "id":"MLA430387888_032012",
   "quality":"",
   "variations":[...]
}

Link a picture to your Item

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

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d
'{"id":"MLA430387888_032012"}'

https://api.mercadolibre.com/items/MLA421101451/pictures?access_token=$ACCESS_TOKEN

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



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 -X POST  \
-H 'content-type: multipart/form-data' \
-F 'file=@FILE' \
https://api.mercadolibre.com/pictures/items/upload?access_token=$ACCESS_TOKEN
Note:
The endpoint only supports multipart uploads (direct data) and for item.

Example:

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

Valid image response:

{
   "id": "959699-MLM43299127002_092020",
   "max_size": "994x1020",
   "dominant_color": null,
   "crop": {
       "y_offset": null,
       "y_size": null,
       "x_offset": null,
       "x_size": null
   },
   "variations": [
       {...},
       {...},
       {...},
       {...},
       {...}
   ]
}

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


Invalid image response:

Important:
Due to the high processing load of the resource, we limit the requests per minute (RPM) for each app_id. If you receive an http error 429 it means that you have exceeded your assigned quota and you will have to wait to retry, or it is because you do not have an assigned quota yet.
{
   "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.

Replace pictures

If you need to replace the current pictures of an item, you need to make a PUT including the Item ID and the picture url, with your access_token like in the example that follows:

curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
'{
  "pictures":[
    {"source":"http://www.apertura.com/export/sites/revistaap/img/Tecnologia/Logo_ML_NUEVO.jpg_33442984.jpg"},
    {"source":"http://appsuser.net/www/wp-content/uploads/2012/10/logo-mercadolibre.jpg"}
  ]
}' https://api.mercadolibre.com/items/{item_id}?access_token=$ACCESS_TOKEN

Important!

  • If you want to replace an image, you should create a new source (re-name image); otherwise, if the same existing source is used with different content the image will not be updated.
  • In case you have a set of images and you wish to perform the following actions: Add an image: you should send the IDs of the uploaded images you wish to keep, along with the source (URL) of the new images. Besides, you can change the order by sending the body of the PUT as you wish to view them.
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -d
'{
"pictures": [{"source": "http://SOURCE_IMAGEN_NUEVA.jpg"},
			{"id": "111111 - IMAGEN_EXISTENTE_111111"},
			{"id": "111111 - IMAGEN_EXISTENTE_111111"},
			{"id": "111111 - IMAGEN_EXISTENTE_111111"}
],

"variations": [{
"id": "16787985187",
"picture_ids": [
		"http://SOURCE_IMAGEN_NUEVA.jpg", 
        "111111 - IMAGEN_EXISTENTE_111111", 
        "111111 - IMAGEN_EXISTENTE_111111", 
        "111111 - IMAGEN_EXISTENTE_111111"]},
{
"id": "16787985190",
"picture_ids": [
		"http://SOURCE_IMAGEN_NUEVA.jpg", 
        "111111 - IMAGEN_EXISTENTE_111111", 
        "111111 - IMAGEN_EXISTENTE_111111", 
        "111111 - IMAGEN_EXISTENTE_111111"]},

{
"id": "16787985193",
"picture_ids": [
		"http://SOURCE_IMAGEN_NUEVA.jpg", 
        "111111 - IMAGEN_EXISTENTE_111111", 
        "111111 - IMAGEN_EXISTENTE_111111", 
        "111111 - IMAGEN_EXISTENTE_111111"]}]
}' http://api.mercadolibre.com/items/ITEM_ID?access_token=$ACCESS_TOKEN

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

Check possible errors

If an image is in error (e.g., “Processing image…”) when uploading an item, you may check the following: 

Call:

curl -X GET https://api.mercadolibre.com/pictures/$PICTURE_ID/errors?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/pictures/970736-MLU11111111111_092017/errors?access_token=$A
CCESS_TOKEN

Response:

{
 "id": "970736-MLU11111111111_092017",
 "source": "https://s3.amazonaws.com/images/pictures/146.111111.jpg",
 "error": {
   "message": "{error_code=response_code, meta={responseCode=403, responseMessage=Forbidden, contentType=application/xml, contentLength=-1}}",
   "items": "MLU111111111"
 }
}

 

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 will be able to 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 "link da imagem" and run the File command to verify the extension.
curl -O "https://s3.amazonaws.com/images/pictures/146.111111.jpg"
file 146.111111.jpg
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

  • HTTP response code references

    The status codes of the HTTP responses indicate whether an HTTP resource was correctly performed. The most frequent cases are:

    Error_code Mensaje del error Descripción Posible solución
    Unable to find valid certification path to requested target El certificado HTTPS no es válido para nuestros servidores. Change the URL, put HTTP (without “s” in the end). In this way, the image is downloaded without validating the certificate.
    301 redirect/moved permanently/etc error_code=content_type,meta={responseCode=301,responseMessage=Moved Permanently, contentType=text/html; charset=UTF-8, contentLength=221, contentEncoding=null} The image you are downloading redirects to another URL (if you test it by browser, you can see the redirection). Don´t work with redirectings. Please, send the last picture URL.
    404 (not found) {error_code=response_code, meta={responseCode=404, responseMessage=Not Found, contentType=application/json, contentLength=30, contentEncoding=null}} the server not found the picture. Verify that the image exists and have our IP´s in the whitelist.
    403 o 401 (Forbidden) It was not possible to download the image because the external server is blocking our access. Verify that you have our ip's in the whitelist.
    Connect timed out It was not possible to connect to the external server to download the picture. Verify that the URL is valid and that the external server has released our IPs.
    Received fatal alert: protocol_version Incompatibility of the ssl protocol by HTTPS. Use HTTP without redirecting.
    Picture wasnt create in buckets The picture do not exist. Verify the page by the browser.

    What are the sizes and versions available in the images

    The maximum size we accept is 1920x1920px (F version) and the minimum is 40x40px (M version). That does not mean that it is not possible to upload images with higher resolution. In that case, the images will be resized for version F. In the case of uploading an image that is smaller than the minimum we allow, the image will be the same size (we will not enlarge the image).



    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.


    Great! now the new picture will be showing on your item. Now you know how to add or replace pictures, remember good pictures will attract more buyers!


    Pictures moderations

    Learn more information about the resource /quality /picture that will allow you to identify the reasons why the item is losing exposure in the listings, that is, it does not meet the image requirements.

or register to recieve the latest news about our API