Media API Overview

The Media API allows users to create, upload, and fetch videos. Users can also create, upload, and fetch documents to attach to their listings. See Business use cases for specifics.

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 and documents using the primary methods and fields listed in the sections that follow.

Methods

The methods in the Media API are:

• video
  • 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.
• document
  • createDocument – This method is used to create a document resource for a document. It creates a document ID based on the metadata sent. This call stages a document to be uploaded, but does not create the document.
  • getDocument – This method is used to retrieve document details using the document ID. This call retrieves basic metadata about a document resource, but does not retrieve (download) the document.
  • uploadDocument – This method uploads a document based on a document source and a provided document ID. Supported file types include the following: .PDF, .JPEG, .JPG, and .PNG.

Primary video fields

The primary fields used in the videos resource 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.
• 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 30 days after its initial upload date.
• Input Stream – The InputStream field contains the input stream of the video file.
• Moderation – The moderation container provides video moderation information, such as the reason(s) why a video is blocked by moderators.
• Play URL – The playURL field contains the playable URL of the video content.
• Playlist – The playList field contains two URLs that link to instances of the streaming video based on the supported protocol.
• 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).
• Size – The size field contains the size, in bytes, of the video to be uploaded.
• 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 video moderation feature.
• 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.
• Title – The title field contains the title of the video.
• Video ID – The video ID field contains the unique id of a video that has been created.

Primary document fields

The primary fields used in the document resource are:

• Document ID - The documentId is returned in the response of a successful createDocument call, both in the documentId field of the response payload and in the location response header. Make sure to capture the document ID value returned to use the other methods in the document resource and to add a document to a listing.

• Document type - The documentType field contains the DocumentTypeEnum specifying the type of document being uploaded. For example, a SAFETY_DATA_SHEET.

• Languages - This array contains the LanguageEnum indicating the language(s) of the document.

Business use cases

Sellers and buyers can use video media to advertise and review items and item features, and document media to provide user guides or product safety and compliance documents.

Videos

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).

Documents

Sellers can upload documents to attach to their listings. For example, product safety compliance documentation or user guides needed for the General Product Safety Regulations (GPSR).

Use the document resource in the Media API to upload document. Add uploaded document to listings with either the Trading API or the Inventory API. See Managing documents for details.

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.