This document provides a brief overview of the process for uploading and promoting video through the Ads API.
The Ads API supports Promoted Video in Tweets and in the following cards:
First, upload the video using the POST media/upload (chunked) endpoint. Using the
media_id, associate the video with an ads account using the POST accounts/:account_id/videos endpoint. The video's
id, sometimes referred to as the
media_key, will be used in subsequent requests. This is a string that begins with an int, is followed by an underscore, and ends with a long value. As an example, see:
Promoted Video in Tweets
To create a Tweet, use the POST accounts/:account_id/tweet endpoint along with the video's
id. In this step, you can also provide a video title, description, and call-to-action (CTA). These values are user-facing.
Promoted Video in Cards
Video App Download and Video Conversation cards support the ability to add a poster images. Upload an image to use in these cards using the POST media/upload endpoint.
Create the card using one of the following endpoints:
- POST accounts/:account_id/cards/video_website
- POST accounts/:account_id/cards/video_app_download
- POST accounts/:account_id/cards/video_conversation
using the video's
id and, optionally, the image's
media_id (for the poster image).
Finally, create the Tweet using the POST accounts/:account_id/tweet endpoint. Cards are attached to Tweets using the
card_uri parameter (if available for the card) or by appending the card's
preview_url to the Tweet
For detailed guidance on video uploading through the API, please see the Video Upload Guide.
Videos can also be promoted as pre-roll assets. See the Video Views Pre-roll Objective Guide for a detailed explanation.
- (As of 2015-10-22) When uploading videos to be used in promoted content, the
media_categoryparameter must be set with a value of
INITcommand requests to the POST media/upload (chunked) endpoint. Using this new param ensures that the video is asynchronously pre-processed and prepared for use in promoted content. The
STATUScommand can be used to check completion of asynchronous processing after video upload.
- The maximum promoted video length currently allowed is 10 mins with a file size of 500MB or less.
- Uploaded video should be either mp4 or mov.
- Uploaded video generally processes quickly, but processing times can vary depending on video length and file size.
- Uploaded poster images should be in png or jpg format. There are no aspect ratio or size requirements, but the poster image will be adjusted to fit the video player.