Managing videos

eBay now allows sellers to upload videos and associate these videos with their listings. To enable this capability, the Media API was created. The Media API has methods to create, upload, and get videos. Video links can be added to listings using the product.videoIds field of the createOrReplaceInventoryItem method in Inventory API, or the Add/Revise/Relist calls of the Trading API with the VideoDetails.VideoID field.

Creating and uploading a video with Media API

The first step in uploading a video to eBay is to first create the video resource using the createVideo method of the Media API.

The request payload of the createVideo method has the following fields:

Field	Description	Required?
title	Title of the video. This should be text only, and markup tags are not supported.	Yes
size	The size of the video in bytes. This value must be accurate or the seller may be blocked from uploading the video. The maximum allowed size for a video is 150MB, or 157,286,400 bytes	Yes
classification	The seller passes in a value of ITEM in this field, which indicates that the video will be associated with an item listing.	Yes
description	This is the user-defined description of the video. Like the title, this should be text only, and markup tags are not supported.	No

If a createVideo method is successful, a 201 Created HTTP status code is returned along with a newly-created video ID value in the Location response header.

The next step is to upload this video using the uploadVideo method. The video ID returned in the createVideo method is passed in as part of the URI, as shown below:

POST https://api.ebay.com/commerce/media/v1/video/{video_id}/upload

The uploadVideo method has no request payload, but you upload a video file in binary format to the endpoint. To accommodate the upload of this binary file, the content-type request header is required, and its value should be set to application/octet-stream.

A successful uploadVideo method will return a 200 OK HTTP status code.

After a successful uploadVideo method, the processing of the file begins. The "happy" status flow of a video upload is PENDING_UPLOAD > PROCESSING > LIVE. If there is an issue with processing, the status may turn to PROCESSING_FAILED, or BLOCKED.

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.

The seller can track the upload status of the video file, and get additional metadata on the uploaded video by using the getVideo method, which is described in the next section.

Retrieving video details with Media API

Sellers can use the getVideo method of the Media API to retrieve details on a specific video that has been uploaded with the Media API. The data that is returned in the response payload will vary based on the processing status. A video in the LIVE state will have more details than a video still in the PROCESSING state.

There is no request payload for the getVideo method, but the video ID of the video must be passed into the call URI, as shown below:

GET https://api.ebay.com/commerce/media/v1/video/{video_id}

The fields returned in the response payload are briefly described below, but please see getVideo reference documentation for more details.

Field	Description	Always Returned?
classification	The value returned in this field indicates the classification of the video. For example, the ITEM indicates that the video will be associated with an item listing.	Yes
description	The user-defined description of the video. This field is only returned if the seller has provided a description of the video.	No
expirationDate	This timestamp indicates the expiration date of the video. Videos are currently set to expire 30 days after they are uploaded.	Yes
playlists	This container is returned for videos in the LIVE state, and it shows the URLs of the videos. The supported video protocols are DASH (Dynamic Adaptive Streaming over HTTP) and HLS (HTTP Live Streaming).	No
size	The size of the video file in bytes.	Yes
status	The current status of the video.	Yes
statusMessage	This text field will provide more details about the video's status.	No
thumbnail.imageUrl	The URL to the video thumbnail image. This will be a generic thumbnail image created by eBay. Custom thumbnail images are not currently supported.	No
title	The title of the video.	Yes
videoId	Unique identifier of the video.	Yes

Adding videos to listings

A video created with the Media API can be added to an eBay listing using the Inventory API or the Add/Revise/Relist calls of the Trading API.

Although a video can be attached to a listing before it is in the LIVE state, the video will not be available for viewing in the listing until it is in the LIVE state. The getVideo method of the Media API can be used to retrieve the status of the video. The status is shown in the status response field.

The following eBay marketplaces support adding a video to a listing:

• EBAY_GB
• EBAY_MOTORS_US
• EBAY_US

When adding, replacing, or removing videos to listings using the Inventory API, use the videoIds field of the createOrReplaceInventoryItem method.

The following Trading API calls also support adding a video to a listing. Also see Replacing or removing videos with Trading API.

• AddFixedPriceItem
• AddItem
• AddItems
• RelistFixedPriceItem
• RelistItem
• ReviseFixedPriceItem
• ReviseItem
• VerifyAddItem
• VerifyAddFixedPriceItem
• VerifyRelistItem

For the Trading API calls above, use the Item.VideoDetails.VideoID to field to add a video to a listing. Below is an example of what this will look like:

<Item>
	...
	<VideoDetails>
	<VideoID>f******************************a</VideoID>
	</VideoDetails>
	...
</Item>

The video should be successfully attached to the listing as long as the VideoID value is valid and belongs to the seller.

A GetItem call can be used by the seller to verify if the video was added to the listing. If the video was successfully added to the listing, the same Item.VideoDetails.VideoID field will be returned in the response. This field will only be returned if the seller of the listing is making the GetItem call.

Replacing or removing videos with Trading API

It is possible to replace or remove videos from listings using the Revise or Relist calls.

To replace a video already attached to the listing, the seller could make a Revise call and just send in another VideoID value. The video specified would replace the existing video.

<Item>
	...
	<VideoDetails>
	<VideoID>h******************************t</VideoID>
	</VideoDetails>
	...
</Item>

To remove a video from the listing using the Revise or Relist calls, the seller can include a DeletedField tag in the request and set its value to Item.VideoDetails.VideoID. So, it will look like the following in a ReviseItem request payload:

<?xml version="1.0" encoding="utf-8"?>
	<ReviseItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
	<DeletedField>Item.VideoDetails.VideoID</DeletedField>
	...
	</ReviseItemRequest>

If the Revise call is successful, the video will be removed from the listing.

Similar to the Add use case, the seller could call GetItem to verify if a video was removed from the listing, or to verify if the existing video was replace by the newly-specified video. If a video was successfully removed, the Item.VideoDetails.VideoID field will not be returned at all in the GetItem response. To verify if a video was successfully replaced, the seller would want to verify the VideoID value returned in the Item.VideoDetails.VideoID field.

Understanding best practices for eBay video services

To ensure that end-users have the best possible experience with eBay video services, follow these best practices: 

• Enable a two-step process to fully leverage the resumable upload feature of Media API. This feature allows users to re-initiate upload from a specific byte offset in cases when an upload is interrupted. More specifically:
  1. Submit metadata about the video being uploaded.
  2. Upload the content.
• Channel the in-stream directly into your Media API integration instead of a file store specific to your application. The uploadVideo Media API method accepts octet streams. This helps avoid storage constraints/costs, and it allows the experience to scale more efficiently.
• Leverage the getVideo Media API method to fetch metadata on the video, and persist the video details against your end-user ID. This should be a lightweight data store, when compared to persisting the video contents for upload while associating the media with a listing. The video metadata, among other information, includes the title, the description provided by the seller, a thumbnail based on the video, and most importantly, the video ID on the eBay platform that is required for associating the uploaded video to a listing.
• Avoid a re-upload bottleneck in your listing experience by surfacing the stored video metadata information to your end-user for easy association with their eBay inventory, thereby promoting media asset re-usability. The video ID need not be in the live status before being associated with a listing; it will automatically appear in the buying experiences when processing and moderation concludes.