Promoted Video

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 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: 13_875943225764098048.

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.

General Information

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_category parameter must be set with a value of amplify_video for all INIT command 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 STATUS command 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.