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
- POST media/upload or POST media/upload (chunked) (upload media)
- POST accounts/:account_id/media_library (add media to the Media Library)
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" --file latte.jpeg --file-field "media"
{
"media_id":966947208837742592,
"media_id_string":"966947208837742592",
"size":74194,
"expires_after_secs":86400,
"image":{
"image_type":"image/jpeg",
"w":800,
"h":418
}
}
Next, using the media ID, add the media to the ads account’s library using the POST accounts/:account_id/media_library endpoint.
twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_key=966947208837742592&name=Latte"
{
"request":{
"params":{
"name":"Latte",
"file_name":"latte.jpeg",
"media_category":"TWEET_IMAGE",
"account_id":"18ce54d4x5t",
"media_key":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_key":"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_id, 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.x.com "/9/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_key":"966947208837742592",
"media_type":"IMAGE",
"updated_at":"2018-02-23T08:06:17Z",
"deleted":false
}
}
Tweet
We can create the Tweet by referencing the images using media_keys.
twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=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":[
966947208837742592
],
"trim_user":true
}
}
}
coffee pic.twitter.com/T772Hx5GNT
— API McTestface (@apimctestface) February 23, 2018
Website Card
All of our cards endpoints support media keys. We will create the website card by referencing the image’s media_key.
twurl -X POST -H ads-api.x.com "/11/accounts/18ce54d4x5t/cards"
{
"name": "components create cards",
"components": [
{
"type": "MEDIA",
"media_key": "3_1323490622599176192"
},
{
"type": "BUTTON",
"label": {
"type": "ENUM",
"value": "INSTALL"
},
"destination": {
"type": "APP",
"country_code": "US",
"googleplay_app_id": "com.twitter.android"
}
}
]
}
We then associate this card with a Tweet using its card_uri.
coffee
— API McTestface (@apimctestface) February 23, 2018