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 in the following cards:

• Video Website
• Video App Download
• Video Conversation

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.