Skip to main content

media APIv1_beta.0.0

Media API

The Media API allows users to create, upload, and fetch videos.

Tip: See Adding a video to your listing in the eBay Seller Center for details about video formatting requirements and restrictions, or visit the relevant eBay site help pages for the region in which the listings will be posted.

This overview covers the following topics:

For more information about using RESTful APIs, see Using eBay Restful APIs.

Technical overview

The Media API allows third-party developers to create, upload, and fetch videos using the primary methods and fields listed in the sections that follow.

Primary methods

The primary methods used for the Media API are:

  • createVideo – This call is used to create videos. It creates a video ID based on the metadata sent.
  • getVideo – This call is used to retrieve videos by means of the video's video ID.
  • uploadVideo – This method uploads a video based on a video source and a provided video ID.

Primary fields

The primary fields used in the Media API methods are:

  • Classification – The classification field contains the purpose of the video content. Currently, the only classification available for videos is ITEM.
  • Description – The description field contains the description of the created or uploaded video. This is an optional field and does not need to be populated in order to create videos.
  • Size – The size field contains the size, in bytes, of the video to be uploaded.
  • Title – The title field contains the title of the video.
  • Protocol – The protocol field contains the protocol for the video playlist. Supported protocols are DASH (Dynamic Adaptive Streaming over HTTP) and HLS (HTTP Live Streaming).
  • Play URL – The playURL field contains the playable URL of the video content.
  • Status Message – The statusMessage field contains additional information on the status. For example, information on why processing might have failed or if the video was blocked.
  • Expiration Date – The expirationDate field contains the expiration date of the video in Coordinated Universal Time (UTC). The expiration of each successfully uploaded video is 365 days (one year) after its initial upload date.
  • Playlist – The playList field contains two URLs that link to instances of the streaming video based on the supported protocol.
  • Status – The status field contains the current status of the video. The available statuses are PENDING UPLOAD, PROCESSING, PROCESSING_FAILED, BLOCKED, and LIVE.
    • When the status of the video is PENDING_UPLOAD, the video is being associated with a video ID and has not been uploaded yet.
    • After a video upload is successfully completed, the status will show as PROCESSING until the video reaches one of the terminal states of LIVE, BLOCKED or PROCESSING_FAILED.

    • When the status of the video is LIVE, this indicates the file has been processed and uploaded successfully. The playList providing URLs for the video in DASH and HLS streaming video protocols will only be generated if the video uploads successfully.
    • There may be issues uploading the video file, leading to a status of PROCESSING_FAILED. If processing fails, it could be because the file is corrupted, is too large, or its size doesn’t match what was provided in the metadata. Refer to the error messages to determine the cause of the video’s failure to upload.
    • This API supports resumable upload. In case of an error during upload, the upload may be resumed starting from the bytes received using appropriate Content-Range and Content-Length headers. For partially uploaded content, an attempt to re-upload will result in an error with the correct Content-Range and Content-Length values for resuming the upload from the correct byte position.

    • A video might be BLOCKED if it contains malware, or if it is blocked by the (future) video moderation feature.
  • Video ID – The video ID field contains the unique id of a video that has been created.
  • Input Stream – The InputStream field contains the input stream of the video file.

Business use cases

Sellers and buyers can use video media in advertising and reviewing items and item features. A buyer may choose to select an item based on a video demonstration of its use and condition when they might not have based on product images or other advertising techniques. Buyers will also be able to review items using video.

Using videos to promote and review items can benefit sellers and buyers in several ways. For example:

  • Sellers can demonstrate the exact condition, size, and uses of the item in the listing.
  • Sellers can stand out from others by providing more detailed visual information for the item or listing.
  • Buyers can provide footage of the items they review and use, including their size, condition, features, and defects (if any).

API restrictions

This section outlines the restrictions for use of the eBay Media API.

Sandbox vs. Production data

The data in the eBay Sandbox environment is static. It can be limited in scope and quantity, and is sometimes simulated or mock data. As a result, you should not assume that data in the Production environment will have the same limitations. Use good coding practices to anticipate the wider range and variability of data that your application is likely to encounter.