eBay Media API
The eBay Media API allows sellers to upload and manage video assets that can be associated with their listings.
OpenAPI Specification
openapi: 3.0.0
info:
title: eBay Media API
description: The Media API allows sellers to create, upload, and fetch videos.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v1_beta.1.1
servers:
- url: https://apim.ebay.com{basePath}
description: Production
variables:
basePath:
default: /commerce/media/v1_beta
paths:
/video:
post:
tags:
- Video
description: This method creates a video. When using this method, specify the <b>title</b>, <b>size</b>, and <b>classification</b> of the video to be created. <b>Description</b> is an optional field for this method.<br /><br /><span class="tablenote"><span style="color:#478415"><strong>Tip:</strong></span> See <a href="https://www.ebay.com/help/selling/listings/creating-managing-listings/add-video-to-listing?id=5272#section3" target="_blank">Adding a video to your listing</a> 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.</span><br /><br />When a video is successfully created, the method returns the HTTP Status Code <code>201 Created.</code>The method also returns the location response header containing the <b>video ID</b>, which you can use to retrieve the video.<br /><br /><span class="tablenote"><span style="color:#004680"><strong>Note:</strong></span> There is no ability to edit metadata on videos at this time. There is also no method to delete videos.</span><br /><br />To upload a created video, use the <a href=" /api-docs/commerce/media/resources/video/methods/uploadVideo" target="_blank">uploadVideo</a> method.
operationId: createVideo
parameters:
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVideoRequest'
required: false
responses:
'201':
description: Created
headers:
Location:
schema:
type: string
description: The created video resource location and the unique <b>video ID</b>.
'400':
description: Bad Request
x-response-codes:
errors:
'190002':
domain: API_MEDIA
category: REQUEST
description: Missing or invalid size. The size of the file (in bytes) is required.
'190003':
domain: API_MEDIA
category: REQUEST
description: Maximum size exceeded for supported uploads. Please refer to the documentation.
'190004':
domain: API_MEDIA
category: REQUEST
description: Title length limit has been exceeded. Please refer to the documentation.
'190005':
domain: API_MEDIA
category: REQUEST
description: Description length exceeded. Please refer to the documentation.
'190006':
domain: API_MEDIA
category: REQUEST
description: A video title is required.
'190014':
domain: API_MEDIA
category: REQUEST
description: A video classification is required.
'190016':
domain: API_MEDIA
category: REQUEST
description: Markups are not permitted in the video title.
'190017':
domain: API_MEDIA
category: REQUEST
description: Markups are not permitted in the video description.
'403':
description: Forbidden
x-response-codes:
errors:
'190013':
domain: API_MEDIA
category: REQUEST
description: Unauthorized access.
'500':
description: Internal Server Error
x-response-codes:
errors:
'190000':
domain: API_MEDIA
category: APPLICATION
description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
/video/{video_id}:
get:
tags:
- Video
description: This method retrieves a video's metadata and content given a specified <b>video ID</b>. The method returns the <b>title</b>, <b>size</b>, <b>classification</b>, <b>description</b>, <b>video ID</b>, <b>playList</b>, <b>status</b>, <b>status message</b> (if any), <b>expiration date</b>, and <b>thumbnail</b> image of the retrieved video. <p>The video’s <b>title</b>, <b>size</b>, <b>classification</b>, and <b>description</b> are set using the <a href=" /api-docs/commerce/media/resources/video/methods/createVideo" target="_blank">createVideo</a> method.</p> <p>The video's <b>playList</b> contains two URLs that link to instances of the streaming video based on the supported protocol.</p><p>The <b>status</b> field contains the current status of the video. After a video upload is successfully completed, the video's <b>status</b> will show as <code>PROCESSING</code> until the video reaches one of the terminal states of <code>LIVE</code>, <code>BLOCKED</code> or <code>PROCESSING_FAILED</code>.<p> If a video's 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.</p> <p> The <b>status message</b> will indicate why a video was blocked from uploading.</p><p>The video’s <b>expiration date</b> is automatically set to 30 days after the video’s initial creation.<p>The video's <b>thumbnail</b> image is automatically generated when the video is created.
operationId: getVideo
parameters:
- name: video_id
in: path
description: The unique identifier of the video to be retrieved.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Video'
'400':
description: Bad Request
'403':
description: Forbidden
x-response-codes:
errors:
'190013':
domain: API_MEDIA
category: REQUEST
description: Unauthorized access.
'404':
description: Not Found
x-response-codes:
errors:
'190001':
domain: API_MEDIA
category: REQUEST
description: The specified video_Id does not exist.
'500':
description: Internal Server Error
x-response-codes:
errors:
'190000':
domain: API_MEDIA
category: APPLICATION
description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
/video/{video_id}/upload:
post:
tags:
- Video
description: This method associates the specified file with the specified <b>video ID</b> and uploads the input file. After the file has been uploaded the processing of the file begins.<br /><br /><span class="tablenote"><span style="color:#004680"><strong>Note:</strong></span> The size of the video to be uploaded must exactly match the size of the video's input stream that was set in the <a href=" /api-docs/commerce/media/resources/video/methods/createVideo" target="_blank">createVideo</a> method. If the sizes do not match, the video will not upload successfully.</span><br /><br />When a video is successfully uploaded, it returns the HTTP Status Code <code>200 OK</code>.<br /><br />The status flow is <code>PENDING_UPLOAD</code> > <code>PROCESSING</code> > <code>LIVE</code>, <code>PROCESSING_FAILED</code>, or <code>BLOCKED</code>. After a video upload is successfully completed, the status will show as <code>PROCESSING</code> until the video reaches one of the terminal states of <code>LIVE</code>, <code>BLOCKED</code>, or <code>PROCESSING_FAILED</code>. If the size information (in bytes) provided is incorrect, the API will throw an error.<br /><br /><span class="tablenote"><span style="color:#478415"><strong>Tip:</strong></span> See <a href="https://www.ebay.com/help/selling/listings/creating-managing-listings/add-video-to-listing?id=5272#section3" target="_blank">Adding a video to your listing</a> 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.</span><br /><br />To retrieve an uploaded video, use the <a href="/api-docs/commerce/media/resources/video/methods/getVideo" target="_blank">getVideo</a> method.
operationId: uploadVideo
parameters:
- name: Content-Length
in: header
description: 'Use this header to specify the content length for the upload. Use Content-Range: bytes {1}-{2}/{3} and Content-Length:{4} headers.<br /><br /><span class="tablenote"><span style="color:#004680"><strong>Note:</strong></span> This header is optional and is only required for <i>resumable</i> uploads (when an upload is interrupted and must be resumed from a certain point).</span>'
required: false
schema:
type: string
- name: Content-Range
in: header
description: Use this header to specify the content range for the upload. The Content-Range should be of the following bytes ((?:[0-9]+-[0-9]+)|\\\\*)/([0-9]+|\\\\*) pattern.<br /><br /><span class="tablenote"><span style="color:#004680"><strong>Note:</strong></span> This header is optional and is only required for <i>resumable</i> uploads (when an upload is interrupted and must be resumed from a certain point).</span>
required: false
schema:
type: string
- name: Content-Type
in: header
description: Use this header to specify the content type for the upload. The Content-Type should be set to <code>application/octet-stream</code>.
required: true
schema:
type: string
- name: video_id
in: path
description: The unique identifier of the video to be uploaded.
required: true
schema:
type: string
requestBody:
description: The request payload for this method is the input stream for the video source. The input source must be an .mp4 file of the type MPEG-4 Part 10 or Advanced Video Coding (MPEG-4 AVC).
content:
application/json:
schema:
description: The request payload for this method is the input stream for the video source. The input source must be an .mp4 file of the type MPEG-4 Part 10 or Advanced Video Coding (MPEG-4 AVC).
$ref: '#/components/schemas/InputStream'
required: false
responses:
'200':
description: OK
'400':
description: Bad Request
x-response-codes:
errors:
'190007':
domain: API_MEDIA
category: REQUEST
description: The content length does not match the content size specified.
'190010':
domain: API_MEDIA
category: REQUEST
description: The video's Content-Range is invalid. The Content-Range should be of the following bytes ((?:[0-9]+-[0-9]+)|\\\\*)/([0-9]+|\\\\*) pattern.
'190012':
domain: API_MEDIA
category: REQUEST
description: The content length of the video is invalid.
'190015':
domain: API_MEDIA
category: REQUEST
description: The uploaded content must match the video size.
'404':
description: Not Found
x-response-codes:
errors:
'190001':
domain: API_MEDIA
category: REQUEST
description: The specified video_Id does not exist.
'409':
description: Conflict
x-response-codes:
errors:
'190011':
domain: API_MEDIA
category: REQUEST
description: The video is already uploaded.
'411':
description: Content Length Required
x-response-codes:
errors:
'190008':
domain: API_MEDIA
category: REQUEST
description: The content length is required.
'416':
description: Range Not Satisfiable
x-response-codes:
errors:
'190009':
domain: API_MEDIA
category: REQUEST
description: 'The Content-Range specified is incorrect. Use Content-Range: bytes {1}}-{2}/{3} and Content-Length:{4} headers.'
'500':
description: Internal Server Error
x-response-codes:
errors:
'190000':
domain: API_MEDIA
category: APPLICATION
description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
components:
schemas:
CreateVideoRequest:
type: object
properties:
classification:
type: array
description: The intended use for this video content. Currently, videos can only be added and associated with eBay listings, so the only supported value is <code>ITEM</code>.
items:
type: string
description: ' For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/commerce/media/types/api:Classification''>eBay API documentation</a>'
description:
type: string
description: The description of the video.
size:
type: integer
description: The size, in bytes, of the video content. <br><br><b>Max:</b> 157,286,400 bytes
format: int32
title:
type: string
description: The title of the video.
description: The request to create a video, which must contain the video's <b>title</b>, <b>size</b>, and <b>classification</b>. <b>Description</b> is an optional field when creating videos.
Error:
type: object
properties:
category:
type: string
description: Identifies the type of erro.
domain:
type: string
description: Name for the primary system where the error occurred. This is relevant for application errors.
errorId:
type: integer
description: A unique number to identify the error.
format: int32
inputRefIds:
type: array
description: An array of request elements most closely associated to the error.
items:
type: string
longMessage:
type: string
description: A more detailed explanation of the error.
message:
type: string
description: Information on how to correct the problem, in the end user's terms and language where applicable.
outputRefIds:
type: array
description: An array of request elements most closely associated to the error.
items:
type: string
parameters:
type: array
description: An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.
items:
$ref: '#/components/schemas/ErrorParameter'
subdomain:
type: string
description: 'Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc.'
description: This type defines the fields that can be returned in an error.
ErrorParameter:
type: object
properties:
name:
type: string
description: The object of the error.
value:
type: string
description: The value of the object.
Image:
type: object
properties:
imageUrl:
type: string
description: The URL to access this image.
description: The automatically generated thumbnail image of the video.
InputStream:
type: object
description: The streaming input of the video source. The input source must be an .mp4 file of the type MPEG-4 Part 10 or Advanced Video Coding (MPEG-4 AVC).
Moderation:
type: object
properties:
rejectReasons:
type: array
description: The reason(s) why the specified video was blocked by moderators.
items:
type: string
description: ' For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/commerce/media/types/api:RejectReasonEnum''>eBay API documentation</a>'
description: A container that provides video moderation information when calling the <strong>getVideo</strong> method.<br /><br />This container is returned if the specified video has been blocked by moderators.<br /><br /><span class="tablenote"><span style="color:#478415"><strong>Tip:</strong></span> See <a href="https://www.ebay.com/help/selling/listings/creating-managing-listings/add-video-to-listing?id=5272#section2" target="_blank">Video moderation and restrictions</a> in the eBay Seller Center for details about video moderation.</span>
Play:
type: object
properties:
playUrl:
type: string
description: The playable URL for this video.
protocol:
type: string
description: "The protocol for the video playlist. Supported protocols are DASH (Dynamic Adaptive Streaming over HTTP) and HLS (HTTP Live Streaming). For implementation help, refer to <a href='https://developer.ebay.com/api-docs/commerce/media/types/api:ProtocolEnum'>eBay API documentation</a>"
description: "The two streaming video URLs available for a successfully uploaded video with a status of <code>LIVE</code>. The supported streaming video protocols are DASH (Dynamic Adaptive Streaming over HTTP) and HLS (HTTP Live Streaming)."
Video:
type: object
properties:
classification:
type: array
description: The intended use for this video content. Currently, videos can only be added and associated with eBay listings, so the only supported value is <code>ITEM</code>.
items:
type: string
description: ' For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/commerce/media/types/api:Classification''>eBay API documentation</a>'
description:
type: string
description: The description of the video. The video description is an optional field that can be set using the <a href=" /api-docs/commerce/media/resources/video/methods/createVideo" target="_blank">createVideo</a> method.
expirationDate:
type: string
description: The expiration date of the video in Coordinated Universal Time (UTC). The video’s expiration date is automatically set to 30 days after the video’s initial upload.
moderation:
description: The video moderation information that is returned if a video is blocked by moderators.<br /><br /><span class="tablenote"><span style="color:#478415"><strong>Tip:</strong></span> See <a href="https://www.ebay.com/help/selling/listings/creating-managing-listings/add-video-to-listing?id=5272#section2" target="_blank">Video moderation and restrictions</a> in the eBay Seller Center for details about video moderation.</span><br /><br />If the video status is <code>BLOCKED</code>, ensure that the video complies with eBay's video formatting and content guidelines. Afterwards, begin the video creation and upload procedure anew using the <strong>createVideo</strong> and <strong>uploadVideo</strong> methods.
$ref: '#/components/schemas/Moderation'
playLists:
type: array
description: "The playlist created for the uploaded video, which provides the streaming video URLs to play the video. The supported streaming video protocols are DASH (Dynamic Adaptive Streaming over HTTP) and HLS (HTTP Live Streaming). The playlist will only be generated if a video is successfully uploaded with a status of <code>LIVE</code>."
items:
$ref: '#/components/schemas/Play'
size:
type: integer
description: The size, in bytes, of the video content.
format: int32
status:
type: string
description: The status of the current video resource. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/commerce/media/types/api:VideoStatusEnum'>eBay API documentation</a>
statusMessage:
type: string
description: The <b>statusMessage</b> field contains additional information on the status. For example, information on why processing might have failed or if the video was blocked.
thumbnail:
description: The URL of the thumbnail image of the video. The thumbnail image's URL must be an eBayPictureURL (EPS URL).
$ref: '#/components/schemas/Image'
title:
type: string
description: The title of the video.
videoId:
type: string
description: The unique ID of the video.
description: A response field that retrieves all the metadata for the video, including its <b>title</b>, <b>classification</b>, <b>size</b>, <b>description</b>, <b>status</b>, <b>status message</b> (if any), and <b>expiration date</b>.
securitySchemes:
api_auth:
type: oauth2
description: The security definitions for this API. Please check individual operations for applicable scopes.
flows:
authorizationCode:
authorizationUrl: https://auth.ebay.com/oauth2/authorize
tokenUrl: https://api.ebay.com/identity/v1/oauth2/token
scopes:
https://api.ebay.com/oauth/api_scope/sell.inventory: View and manage your inventory and offers
tags:
- name: Video