Announcement: Setting video poster images



Starting today, users will be able to set poster images (thumbnails) for videos using the poster_image_media_id parameter on the POST accounts/:account_id/videos and PUT accounts/:account_id/videos/:id endpoints. Using a poster image with different dimensions than the video dimensions may cause the thumbnail to be misaligned or cropped, so we strongly encourage the use of the same dimensions when possible. As before, if this is not specified, the first frame will be used by default.

Note that only the original owner, i.e., the authenticated user at the time of the upload, can set or modify the poster image. Because of this, videos should always be uploaded by the full promotable user on the account.

A video with a custom poster image:

Twitter Ads API Team

Upload the poster image using the POST media/upload endpoint, as follows:

$ twurl -X POST -H "/1.1/media/upload.json" --file twitter.png --file-field "media"
  "media_id": 861798310549397504,
  "media_id_string": "861798310549397504",
  "size": 22836,
  "expires_after_secs": 86400,
  "image": {
    "image_type": "image/png",
    "w": 1920,
    "h": 1080

After uploading the video using the POST media/upload endpoint, check it’s status using the GET media/upload endpoint. Once the state shows a value of succeeded, the video is ready to be used.

$ twurl -H "/1.1/media/upload.json?command=STATUS&media_id=861797806486323200"
  "media_id": 861797806486323200,
  "media_id_string": "861797806486323200",
  "size": 13005055,
  "expires_after_secs": 15551974,
  "video": {
    "video_type": "video/mp4"
  "processing_info": {
    "state": "succeeded",
    "progress_percent": 100

Finally, use the POST accounts/:account_id/videos endpoint to associate the video with the ads account and to set the poster image.

$ twurl -X POST -H "/1/accounts/18ce54d4x5t/videos?video_media_id=861797806486323200&poster_image_media_id=861798310549397504"
  "data_type": "video",
  "data": {
    "id": "13_861797806486323200"
  "request": {
    "params": {
      "video_media_id": 861797806486323200,
      "poster_image_media_id": 861798310549397504,
      "account_id": "18ce54d4x5t"

Video Thumbnails



We’ve removed this restriction. Now, an additional owner can set or modify the poster image. This only applies to videos uploaded on or after 2017-06-19. Make sure to specify the additional_owners in both the video’s POST media/upload (INIT) request and the image’s POST media/upload request.