Multiple Media Entities in Tweets for the REST API
We are ready to launch a new extended entities representation to support our multiple images per tweet feature. See https://blog.twitter.com/2014/photos-just-got-more-social for the blog post announcing this for users.
GETting Extended Entities via the API
In addition to the entities you can usually find in the JSON representation of a tweet as documented in Entities in Twitter Objects, we are adding a new object, extended_entities, giving us more latitude in what metadata we can return for developers and partners willing to develop support for new bleeding edge features. The first use case for extended_entities is a collection of multiple images referenced in a tweet (sample output below).
We are introducing extended_entities to support the representation of multiple media entities in the text of the tweet as a single URL. One important detail to understand, the ranges for these entities will overlap, meaning that multiple images will be represented by a single link, whereas before each image had a text range/url.
Clients that do not expect overlapping ranges will need to be updated to support extended_entities and multiple media tweets. The format of media entities remains unchanged except for this overlap. As long as you fall back to entities if you can not support extended_entities, you should be fine. The legacy entities is guaranteed to contain at most one single entry in its array, while the new extended_entities will contain an array of all entities associated with a tweet, up to a maximum of 28. Entities copied from other tweets will contain a source_status_id field with the ID of the original tweet.
Today the only type exposed in our entities is photo, however with the addition of extended_entities we plan to expand the types of media we expose. Developers should actively use the type attribute from the media exposed to validate you are handling the types properly, as non-photo media are on the way.
POSTing multiple media files
Uploading multiple media files is a 2 step process, you first need to POST multipart/form-data or base64 encoded files to https://upload.twitter.com/1.1/media/upload.json and then collect the resulting IDs to pass as a comma separated list of media_ids for all the files you want to attach to your POST statuses/update. Uploaded media files will be available for attachment for 60 minutes before they are flushed from the servers (if not attached to a tweet). Note that you need to call the upload endpoint once per media file you want to upload (so to upload three media files, call the upload endpoint three times, storing the media_ids ready to be attached to your POST statuses/update).
See sample queries section below for examples of calls and results.
What's next?
Multiple images is the only new extended_entities feature we are shipping now but we plan to use this extension process to improve the API over the course of the next months.
Feel free to ask us any questions you might have while implementing these in you app.
Sample Query
GETting Statuses with extended_entities
https://api.twitter.com/1.1/statuses/show.json?id=449660889793581056
Sample output (partial)
"entities": {
"hashtags": [],
"media": [
{"display_url": "pic.twitter.com/fxmuQN9JL9",
"expanded_url": "http://twitter.com/FLOTUS/status/449660889793581056/photo/1",
"id": 449660809380380673,
"id_str": "449660809380380673",
"indices": [
121,143],"media_url": "http://pbs.twimg.com/media/Bj2EH6yIQAEYvxu.jpg",
"media_url_https": "https://pbs.twimg.com/media/Bj2EH6yIQAEYvxu.jpg",
"sizes": {
"large": {
"h": 426,
"resize": "fit",
"w": 640
},"medium": {
"h": 399,
"resize": "fit",
"w": 600
},"small": {
"h": 226,
"resize": "fit",
"w": 340
},"thumb": {
"h": 150,
"resize": "crop",
"w": 150
}},"type": "photo",
"url": "http://t.co/fxmuQN9JL9"
}],"symbols": [],
"urls": [],
"user_mentions": []
},"extended_entities": {
"media": [
{"display_url": "pic.twitter.com/fxmuQN9JL9",
"expanded_url": "http://twitter.com/FLOTUS/status/449660889793581056/photo/1",
"id": 449660809380380673,
"id_str": "449660809380380673",
"indices": [
121,143],"media_url": "http://pbs.twimg.com/media/Bj2EH6yIQAEYvxu.jpg",
"media_url_https": "https://pbs.twimg.com/media/Bj2EH6yIQAEYvxu.jpg",
"sizes": {
"large": {
"h": 426,
"resize": "fit",
"w": 640
},"medium": {
"h": 399,
"resize": "fit",
"w": 600
},"small": {
"h": 226,
"resize": "fit",
"w": 340
},"thumb": {
"h": 150,
"resize": "crop",
"w": 150
}},"type": "photo",
"url": "http://t.co/fxmuQN9JL9"
},{"display_url": "pic.twitter.com/fxmuQN9JL9",
"expanded_url": "http://twitter.com/FLOTUS/status/449660889793581056/photo/1",
},"id": 449660806754738177,
"id_str": "449660806754738177",
"indices": [
121,143],"media_url": "http://pbs.twimg.com/media/Bj2EHxAIIAE8dtg.jpg",
"media_url_https": "https://pbs.twimg.com/media/Bj2EHxAIIAE8dtg.jpg",
"sizes": {
"large": {
"h": 426,
"resize": "fit",
"w": 640
},"medium": {
"h": 399,
"resize": "fit",
"w": 600
},"small": {
"h": 226,
"resize": "fit",
"w": 340
},"thumb": {
"h": 150,
"resize": "crop",
"w": 150
}},"type": "photo",
"url": "http://t.co/fxmuQN9JL9"
},{"display_url": "pic.twitter.com/fxmuQN9JL9",
"expanded_url": "http://twitter.com/FLOTUS/status/449660889793581056/photo/1",
"id": 449660808537333761,
"id_str": "449660808537333761",
"indices": [
121,143],"media_url": "http://pbs.twimg.com/media/Bj2EH3pIYAE4LQn.jpg",
"media_url_https": "https://pbs.twimg.com/media/Bj2EH3pIYAE4LQn.jpg",
"sizes": {
"large": {
"h": 427,
"resize": "fit",
"w": 640
},"medium": {
"h": 400,
"resize": "fit",
"w": 600
},"small": {
"h": 227,
"resize": "fit",
"w": 340
},"thumb": {
"h": 150,
"resize": "crop",
"w": 150
}},"type": "photo",
"url": "http://t.co/fxmuQN9JL9"
},{"display_url": "pic.twitter.com/fxmuQN9JL9",
"expanded_url": "http://twitter.com/FLOTUS/status/449660889793581056/photo/1",
"id": 449660877097406464,
"id_str": "449660877097406464",
"indices": [
121,143],"media_url": "http://pbs.twimg.com/media/Bj2EL3DIEAAzGAX.jpg",
"media_url_https": "https://pbs.twimg.com/media/Bj2EL3DIEAAzGAX.jpg",
"sizes": {
"large": {
"h": 426,
"resize": "fit",
"w": 640
},"medium": {
"h": 399,
"resize": "fit",
"w": 600
},"small": {
"h": 226,
"resize": "fit",
"w": 340
},"thumb": {
"h": 150,
"resize": "crop",
"w": 150
}},"type": "photo",
"url": "http://t.co/fxmuQN9JL9"
}]},
Uploading files via POST and attaching media_ids to a new Status
Note that if you're uploading a base64-encoded, the param name for this endpoint will be media_data rather than media, which is used for raw images.
Examples using Twurl for sake of simplicity.First, upload your file(s).
twurl -H upload.twitter.com "/1.1/media/upload.json" -f /path/to/your/file-1.jpg -F media -X POST
Result
{"image": {
"w": 1546,
"h": 1024,
"image_type": "image\/jpeg"
},"media_id": 460938773744717825,
"media_id_string": "460938773744717825",
"size": 530963
}
Then, POST the status update with media_ids (comma separated list, with trim_user to keep the output brief)
twurl "/1.1/statuses/update.json" -d "media_ids=460938773744717825,460938635315916800&status=Combined.&trim_user=1"
Result
{"created_at": "Tue Apr 29 00:50:10 +0000 2014",
"id": 460944092554227713,
"id_str": "460944092554227713",
"text": "Combined. http:\/\/t.co\/fFJqqT1A4j",
"source": "\u003ca href=\"http:\/\/twitter.com\/geekculturejam\" rel=\"nofollow\"\u003eCultureJam\u003c\/a\u003e",
"truncated": false,
"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": 657693,
"id_str": "657693"
},"geo": null,
"coordinates": null,
"place": null,
"contributors": null,
"retweet_count": 0,
"favorite_count": 0,
"entities": {
"hashtags": [],
"symbols": [],
"urls": [],
"user_mentions": [],
"media": [
{"id": 460938773744717825,
"id_str": "460938773744717825",
"indices": [
10,32],"media_url": "http:\/\/pbs.twimg.com\/media\/BmWVX2BCEAEx4MK.jpg",
"media_url_https": "https:\/\/pbs.twimg.com\/media\/BmWVX2BCEAEx4MK.jpg",
"url": "http:\/\/t.co\/fFJqqT1A4j",
"display_url": "pic.twitter.com\/fFJqqT1A4j",
"expanded_url": "http:\/\/twitter.com\/froginthevalley\/status\/460944092554227713\/photo\/1",
"type": "photo",
"sizes": {
"medium": {
"w": 599,
"h": 397,
"resize": "fit"
},"thumb": {
"w": 150,
"h": 150,
"resize": "crop"
},"small": {
"w": 340,
"h": 225,
"resize": "fit"
},"large": {
"w": 1023,
"h": 678,
"resize": "fit"
}}}]},"extended_entities": {
"media": [
{"id": 460938773744717825,
"id_str": "460938773744717825",
"indices": [
10,32],"media_url": "http:\/\/pbs.twimg.com\/media\/BmWVX2BCEAEx4MK.jpg",
"media_url_https": "https:\/\/pbs.twimg.com\/media\/BmWVX2BCEAEx4MK.jpg",
"url": "http:\/\/t.co\/fFJqqT1A4j",
"display_url": "pic.twitter.com\/fFJqqT1A4j",
"expanded_url": "http:\/\/twitter.com\/froginthevalley\/status\/460944092554227713\/photo\/1",
"type": "photo",
"sizes": {
"medium": {
"w": 599,
"h": 397,
"resize": "fit"
},"thumb": {
"w": 150,
"h": 150,
"resize": "crop"
},"small": {
"w": 340,
"h": 225,
"resize": "fit"
},"large": {
"w": 1023,
"h": 678,
"resize": "fit"
}}},{"id": 460938635315916800,
"id_str": "460938635315916800",
"indices": [
10,32],"media_url": "http:\/\/pbs.twimg.com\/media\/BmWVPyVCMAAeAwI.jpg",
"media_url_https": "https:\/\/pbs.twimg.com\/media\/BmWVPyVCMAAeAwI.jpg",
"url": "http:\/\/t.co\/fFJqqT1A4j",
"display_url": "pic.twitter.com\/fFJqqT1A4j",
"expanded_url": "http:\/\/twitter.com\/froginthevalley\/status\/460944092554227713\/photo\/1",
"type": "photo",
"sizes": {
"medium": {
"w": 600,
"h": 600,
"resize": "fit"
},"thumb": {
"w": 150,
"h": 150,
"resize": "crop"
},"large": {
"w": 1024,
"h": 1024,
"resize": "fit"
},"small": {
"w": 340,
"h": 340,
"resize": "fit"
}}}]},"favorited": false,
"retweeted": false,
"possibly_sensitive": false,
"lang": "en"
}
VoilĂ ! Have fun and send us your questions at @TwitterDev.

