Skip to main content

Sellers can upload images through the Media API image resource, which has methods to create images from files or URLs, and to retrieve image details.

If either create image call is successful, a 201 Created HTTP status code is returned along with a newly-created image ID URI value in the location response header, which you can use to retrieve the image resource containing the actual EPS image URL to be used with use the getImage method. This value should be stored/kept by the seller.

Important! Make sure to capture the image ID URI returned in the location header of the response to the create method called. The URI returned will be in the following format:

https://apim.ebay.com/commerce/media/v1_beta/image/{image_id}

You can capture the entire URI, or just save the {image_id} only. This image ID URI to the image resource containing the actual EPS image URL is required to use the getImage method.

The response payload of a successful create call contains the imageUrl and its expiration date. This URL is the actual EPS image URL used to add the image with to listings (same URL returned when calling the getImage method). Add the image to inventory items using the createOrReplaceInventoryItem method in Inventory API (in the product.imageUrls array), or using the Add/Revise/Relist calls of the Trading API in the Item.PictureDetails container (for example, in the AddFixedPriceItem call you would use the Item.PictureDetails.PictureURL field).

Image requirements

Every listing is required to include at least one picture of the item, but providing lots of high-quality pictures is a great way to help sell your item.

For most categories, sellers can include up to 24 pictures in one listing at no cost. However it is important to be aware of the following exceptions:

  • Multiple SKU/Multiple-variation listings: A maximum of 12 pictures may be used per variation.

  • Motor Vehicle listings: The number of pictures included depends on the selected vehicle package. For complete information, refer to Fees for selling vehicles on eBay Motors.

For additional information, sellers can refer to eBay's picture policy and related resources.

eBay Picture Services (EPS) supports the uploading of image data in JPG, GIF, PNG, BMP, TIFF, AVIF, HEIC, and WEBP formats. Error 190203 is returned if you upload images in another format (such as PSD). EPS stores successfully processed images at sizes and compression settings designed to provide the best trade-off between image quality and page-load times. See the following notes for additional image requirements.

Note: All images must comply with eBay's picture requirements. If a dimension or file size limit is exceeded, the errors returned will include the applicable limits. Image processing issues, such as thumbnail or gallery image generation, can result.

  • Error 190201 is returned if the image file size is larger than the maximum file size allowed. For example, if the maximum original file size is 12 MB, images with a file size greater than this are not acceptable.

  • Error 190202 is returned if the height + width dimension limit is exceeded. For example, if the maximum image dimension limit is 15,000 pixels (height + width), an 800 x 800 image is acceptable (800 + 800 = 1600, which is less than 15,000), but an 8000 x 8000 image is not (8000 + 8000 = 16,000, which is greater than 15,000).

  • Error 190203 is returned if the image is in an image format that is not supported.

  • Error 190204 is returned if the image cannot be downloaded from the URL, or if the provided URL is not secured using HTTPS (HTTP is not permitted).


Note: Uploaded images may be converted when uploaded:

  • GIF images, PNG images, and JPG images retain their original format
  • Other non-JPG format files are converted to JPG

EPS downscales and compresses the picture and stores it at the different sizes in the image set. If the dimensions of an uploaded picture are less than a size that is stored in EPS, the upload will be accepted, and the stored picture will be the same dimensions as the uploaded picture. In this case, image quality of the stored picture is likely to be degraded.

Create an image from a file

Create an image resource from a file using the createImageFromFile method. When uploading your image file, this method does not use a JSON payload, but uploads files using multipart/form-data with information about the form data provided by key-value pairs. The following table contains the description of the available key.

Form data key and value description

Key

Type

Description

image

string

Image data.

For example, to specify a local file:
image: @"/C:/Users/.../sample_picture.jpg"

Occurrence: Required

Create an image from a URL

Create an image resource from a URL using the createImageFromUrl method to upload a picture to eBay Picture Services (EPS). Specify the location of the picture from an external web server in the imageUrl field of the request payload.

Retrieve image details

To retrieve a created image’s details, including its expiration date, call the getImage method and specifying the image ID URI. This ID was provided in the location header of the response to the create method called, either createImageFromFile or createImageFromUrl.