Media Library

Introduction

The Media Library endpoints provide the ability to manage images, GIFs, and videos for Twitter Ads accounts. Media assets in the library can be used in Tweets and to create cards. They can also be reused in multiple creatives, eliminating the need to upload the same asset multiple times.

API Endpoints

Adding to the Library

Adding media to the library is a two-step process. First, upload the asset using either the POST media/upload endpoint or the POST media/upload (chunked) set of endpoints. (See the Chunked media upload guide for details on our multi-part upload process.)

twurl -X POST -H upload.twitter.com "/1.1/media/upload.json?additional_owners=756201191646691328&media_category=TWEET_IMAGE" --file latte.jpeg --file-field "media"

{  
   "media_id":966947208837742592,
   "media_id_string":"966947208837742592",
   "media_key":"3_966947208837742592",
   "size":74194,
   "expires_after_secs":86400,
   "image":{  
      "image_type":"image/jpeg",
      "w":800,
      "h":418
   }
}

Next, using the media key, add the media to the ads account’s library using the POST accounts/:account_id/media_library endpoint.

twurl -X POST -H ads-api.twitter.com "/6/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_key=3_966947208837742592&name=Latte"

{  
   "request":{  
      "params":{  
         "name":"Latte",
         "file_name":"latte.jpeg",
         "media_category":"TWEET_IMAGE",
         "account_id":"18ce54d4x5t",
         "media_key": "3_966947208837742592"
      }
   },
   "data":{  
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_id":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

Note: Tweeting images, GIFs, or videos directly after the upload also adds media to the library.

Request Parameters

All Media Library POST requests require a media identifier. This value is returned during the upload step. When using the media_key, as in the example above, a media_category must also be specified. There are four possible category values: AMPLIFY_VIDEO, TWEET_GIF, TWEET_IMAGE, and TWEET_VIDEO.

Optionally, name and file_name values can be set for objects in the Media Library. These attributes help users distinguish between media variants in the library.

For videos, it’s also possible to set a title and a description. They values are intended to be passed as the video_title and video_description request parameters with the POST accounts/:account_id/tweet endpoint. In the Tweet, this text appears under the video.

Attributes

The Media Library, formally introduces the concept of the media_key. This is the unique identifier for objects in the library. Media keys are string values in the following format: 13_875943225764098048. These are fully supported in all of our card endpoints.

In addition, the Media Library response includes the media_id, represented as a string. This is included for resources that do not currently accept a media key: Tweets*, Tweet preview*, and Scheduled Tweets. We are working toward supporting media keys everywhere.

The aspect_ratio attribute is returned for GIFs and videos. This can be used to filter media for use in cards that only accept particular aspect ratios.

*These endpoints support the video_id parameter, which is a media key.

Usage

In this section, the following image will be used in a Tweet and to create a website card.

twurl -H ads-api.twitter.com "/6/accounts/18ce54d4x5t/media_library/3_966947208837742592"

{  
   "request":{  
      "params":{  
         "account_id":"18ce54d4x5t",
         "media_key":"3_966947208837742592"
      }
   },
   "data":{  
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_id":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

 

Tweet

The POST accounts/:account_id/tweet endpoint supports specifying images using media keys. 

twurl -X POST -H ads-api.twitter.com "/6/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=3_966947208837742592&as_user_id=756201191646691328&trim_user=true"

{  
   "data":{  
      "created_at":"Fri Feb 23 08:20:05 +0000 2018",
      "id":966950781302665218,
      "id_str":"966950781302665218",
      "text":"coffee https://t.co/T772Hx5GNT",
      "truncated":false,
      "entities":{  
         "hashtags":[  

         ],
         "symbols":[  

         ],
         "user_mentions":[  

         ],
         "urls":[  

         ],
         "media":[  
            {  
               "id":966947208837742592,
               "id_str":"966947208837742592",
               "indices":[  
                  7,
                  30
               ],
               "media_url":"http://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "media_url_https":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "url":"https://t.co/T772Hx5GNT",
               "display_url":"pic.twitter.com/T772Hx5GNT",
               "expanded_url":"https://twitter.com/apimctestface/status/966950781302665218/photo/1",
               "type":"photo",
               "sizes":{  
                  "thumb":{  
                     "w":150,
                     "h":150,
                     "resize":"crop"
                  },
                  "large":{  
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "medium":{  
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "small":{  
                     "w":680,
                     "h":355,
                     "resize":"fit"
                  }
               }
            }
         ]
      },
      "source":"Ads API Internal Test App",
      "in_reply_to_status_id":null,
      "in_reply_to_status_id_str":null,
      "in_reply_to_user_id":null,
      "in_reply_to_user_id_str":null,
      "in_reply_to_screen_name":null,
      "user":{  
         "id":756201191646691328,
         "id_str":"756201191646691328"
      },
      "geo":null,
      "coordinates":null,
      "place":null,
      "contributors":[  
         2417045708
      ],
      "retweet_count":0,
      "favorite_count":0,
      "favorited":false,
      "retweeted":false,
      "possibly_sensitive":false,
      "scopes":{  
         "followers":false
      },
      "lang":"en"
   },
   "request":{  
      "params":{  
         "as_user_id":756201191646691328,
         "text":"coffee",
         "account_id":"18ce54d4x5t",
         "media_keys":[  
            3_966947208837742592
         ],
         "trim_user":true
      }
   }
}

 

Website Card

All of our cards endpoints support media keys. We will create the website card by referencing the image’s media_key.

Note: It is not possible to use a Media Library image's media_id to create a card.

twurl -X POST -H ads-api.twitter.com "/6/accounts/18ce54d4x5t/cards/website?name=Media Library latte card&website_title=Use the Media Library&media_key=3_966947208837742592&website_url=https://developer.twitter.com/en/docs/ads/creatives/api-reference/media-library"

{  
   "data":{  
      "name":"Media Library latte card",
      "website_shortened_url":"https://t.co/mCvkfGSl5b",
      "image_display_height":"418",
      "image":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "website_display_url":"developer.twitter.com",
      "id":"5dkat",
      "website_dest_url":"https://developer.twitter.com/en/docs/ads/creatives/api-reference/media-library",
      "created_at":"2018-02-23T08:25:27Z",
      "image_display_width":"800",
      "website_title":"Use the Media Library",
      "card_uri":"card://966952130299834373",
      "website_url":"https://developer.twitter.com/en/docs/ads/creatives/api-reference/media-library",
      "updated_at":"2018-02-23T08:25:27Z",
      "deleted":false,
      "card_type":"WEBSITE"
   },
   "request":{  
      "params":{  
         "name":"Media Library latte card",
         "website_shortened_url":"https://t.co/mCvkfGSl5b",
         "image_display_height":"418",
         "image":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
         "image_media_key":"3_966947208837742592",
         "website_display_url":"developer.twitter.com",
         "account_id":"18ce54d4x5t",
         "website_dest_url":"https://developer.twitter.com/en/docs/ads/creatives/api-reference/media-library",
         "image_display_width":"800",
         "website_title":"Use the Media Library",
         "website_url":"https://developer.twitter.com/en/docs/ads/creatives/api-reference/media-library",
         "card_type":"WEBSITE"
      }
   }
}

We then associate this card with a Tweet using its card_uri.