The Wayback Machine - https://web-wp.archive.org/web/20140716090633/https://dev.twitter.com/docs/api/multiple-media-extended-entities

Multiple Media Entities in Statuses

Updated on Tue, 2014-05-27 07:40

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)

  1.    "entities": {
  2.         "hashtags": [],
  3.         "media": [
  4.             {
  5.                 "display_url": "pic.twitter.com/fxmuQN9JL9",
  6.                 "expanded_url": "http://twitter.com/FLOTUS/status/449660889793581056/photo/1",
  7.                 "id": 449660809380380673,
  8.                 "id_str": "449660809380380673",
  9.                 "indices": [
  10.                     121,
  11.                     143
  12.                 ],
  13.                 "media_url": "http://pbs.twimg.com/media/Bj2EH6yIQAEYvxu.jpg",
  14.                 "media_url_https": "https://pbs.twimg.com/media/Bj2EH6yIQAEYvxu.jpg",
  15.                 "sizes": {
  16.                     "large": {
  17.                         "h": 426,
  18.                         "resize": "fit",
  19.                         "w": 640
  20.                     },
  21.                     "medium": {
  22.                         "h": 399,
  23.                         "resize": "fit",
  24.                         "w": 600
  25.                     },
  26.                     "small": {
  27.                         "h": 226,
  28.                         "resize": "fit",
  29.                         "w": 340
  30.                     },
  31.                     "thumb": {
  32.                         "h": 150,
  33.                         "resize": "crop",
  34.                         "w": 150
  35.                     }
  36.                 },
  37.                 "type": "photo",
  38.                 "url": "http://t.co/fxmuQN9JL9"
  39.             }
  40.         ],
  41.         "symbols": [],
  42.         "urls": [],
  43.         "user_mentions": []
  44.     },
  45.     "extended_entities": {
  46.         "media": [
  47.             {
  48.                 "display_url": "pic.twitter.com/fxmuQN9JL9",
  49.                 "expanded_url": "http://twitter.com/FLOTUS/status/449660889793581056/photo/1",
  50.                 "id": 449660809380380673,
  51.                 "id_str": "449660809380380673",
  52.                 "indices": [
  53.                     121,
  54.                     143
  55.                 ],
  56.                 "media_url": "http://pbs.twimg.com/media/Bj2EH6yIQAEYvxu.jpg",
  57.                 "media_url_https": "https://pbs.twimg.com/media/Bj2EH6yIQAEYvxu.jpg",
  58.                 "sizes": {
  59.                     "large": {
  60.                         "h": 426,
  61.                         "resize": "fit",
  62.                         "w": 640
  63.                     },
  64.                     "medium": {
  65.                         "h": 399,
  66.                         "resize": "fit",
  67.                         "w": 600
  68.                     },
  69.                     "small": {
  70.                         "h": 226,
  71.                         "resize": "fit",
  72.                         "w": 340
  73.                     },
  74.                     "thumb": {
  75.                         "h": 150,
  76.                         "resize": "crop",
  77.                         "w": 150
  78.                     }
  79.                 },
  80.                 "type": "photo",
  81.                 "url": "http://t.co/fxmuQN9JL9"
  82.             },
  83.             {
  84.                 "display_url": "pic.twitter.com/fxmuQN9JL9",
  85.                 "expanded_url": "http://twitter.com/FLOTUS/status/449660889793581056/photo/1",
  86.                 },
  87.                 "id": 449660806754738177,
  88.                 "id_str": "449660806754738177",
  89.                 "indices": [
  90.                     121,
  91.                     143
  92.                 ],
  93.                 "media_url": "http://pbs.twimg.com/media/Bj2EHxAIIAE8dtg.jpg",
  94.                 "media_url_https": "https://pbs.twimg.com/media/Bj2EHxAIIAE8dtg.jpg",
  95.                 "sizes": {
  96.                     "large": {
  97.                         "h": 426,
  98.                         "resize": "fit",
  99.                         "w": 640
  100.                     },
  101.                     "medium": {
  102.                         "h": 399,
  103.                         "resize": "fit",
  104.                         "w": 600
  105.                     },
  106.                     "small": {
  107.                         "h": 226,
  108.                         "resize": "fit",
  109.                         "w": 340
  110.                     },
  111.                     "thumb": {
  112.                         "h": 150,
  113.                         "resize": "crop",
  114.                         "w": 150
  115.                     }
  116.                 },
  117.                 "type": "photo",
  118.                 "url": "http://t.co/fxmuQN9JL9"
  119.             },
  120.             {
  121.                 "display_url": "pic.twitter.com/fxmuQN9JL9",
  122.                 "expanded_url": "http://twitter.com/FLOTUS/status/449660889793581056/photo/1",
  123.                 "id": 449660808537333761,
  124.                 "id_str": "449660808537333761",
  125.                 "indices": [
  126.                     121,
  127.                     143
  128.                 ],
  129.                 "media_url": "http://pbs.twimg.com/media/Bj2EH3pIYAE4LQn.jpg",
  130.                 "media_url_https": "https://pbs.twimg.com/media/Bj2EH3pIYAE4LQn.jpg",
  131.                 "sizes": {
  132.                     "large": {
  133.                         "h": 427,
  134.                         "resize": "fit",
  135.                         "w": 640
  136.                     },
  137.                     "medium": {
  138.                         "h": 400,
  139.                         "resize": "fit",
  140.                         "w": 600
  141.                     },
  142.                     "small": {
  143.                         "h": 227,
  144.                         "resize": "fit",
  145.                         "w": 340
  146.                     },
  147.                     "thumb": {
  148.                         "h": 150,
  149.                         "resize": "crop",
  150.                         "w": 150
  151.                     }
  152.                 },
  153.                 "type": "photo",
  154.                 "url": "http://t.co/fxmuQN9JL9"
  155.             },
  156.             {
  157.                 "display_url": "pic.twitter.com/fxmuQN9JL9",
  158.                 "expanded_url": "http://twitter.com/FLOTUS/status/449660889793581056/photo/1",
  159.                 "id": 449660877097406464,
  160.                 "id_str": "449660877097406464",
  161.                 "indices": [
  162.                     121,
  163.                     143
  164.                 ],
  165.                 "media_url": "http://pbs.twimg.com/media/Bj2EL3DIEAAzGAX.jpg",
  166.                 "media_url_https": "https://pbs.twimg.com/media/Bj2EL3DIEAAzGAX.jpg",
  167.                 "sizes": {
  168.                     "large": {
  169.                         "h": 426,
  170.                         "resize": "fit",
  171.                         "w": 640
  172.                     },
  173.                     "medium": {
  174.                         "h": 399,
  175.                         "resize": "fit",
  176.                         "w": 600
  177.                     },
  178.                     "small": {
  179.                         "h": 226,
  180.                         "resize": "fit",
  181.                         "w": 340
  182.                     },
  183.                     "thumb": {
  184.                         "h": 150,
  185.                         "resize": "crop",
  186.                         "w": 150
  187.                     }
  188.                 },
  189.                 "type": "photo",
  190.                 "url": "http://t.co/fxmuQN9JL9"
  191.             }
  192.         ]
  193.     },

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

  1. {
  2.   "image": {
  3.     "w": 1546,
  4.     "h": 1024,
  5.     "image_type": "image\/jpeg"
  6.   },
  7.   "media_id": 460938773744717825,
  8.   "media_id_string": "460938773744717825",
  9.   "size": 530963
  10. }

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

  1. {
  2.   "created_at": "Tue Apr 29 00:50:10 +0000 2014",
  3.   "id": 460944092554227713,
  4.   "id_str": "460944092554227713",
  5.   "text": "Combined. http:\/\/t.co\/fFJqqT1A4j",
  6.   "source": "\u003ca href=\"http:\/\/twitter.com\/geekculturejam\" rel=\"nofollow\"\u003eCultureJam\u003c\/a\u003e",
  7.   "truncated": false,
  8.   "in_reply_to_status_id": null,
  9.   "in_reply_to_status_id_str": null,
  10.   "in_reply_to_user_id": null,
  11.   "in_reply_to_user_id_str": null,
  12.   "in_reply_to_screen_name": null,
  13.   "user": {
  14.     "id": 657693,
  15.     "id_str": "657693"
  16.   },
  17.   "geo": null,
  18.   "coordinates": null,
  19.   "place": null,
  20.   "contributors": null,
  21.   "retweet_count": 0,
  22.   "favorite_count": 0,
  23.   "entities": {
  24.     "hashtags": [],
  25.     "symbols": [],
  26.     "urls": [],
  27.     "user_mentions": [],
  28.     "media": [
  29.       {
  30.         "id": 460938773744717825,
  31.         "id_str": "460938773744717825",
  32.         "indices": [
  33.           10,
  34.           32
  35.         ],
  36.         "media_url": "http:\/\/pbs.twimg.com\/media\/BmWVX2BCEAEx4MK.jpg",
  37.         "media_url_https": "https:\/\/pbs.twimg.com\/media\/BmWVX2BCEAEx4MK.jpg",
  38.         "url": "http:\/\/t.co\/fFJqqT1A4j",
  39.         "display_url": "pic.twitter.com\/fFJqqT1A4j",
  40.         "expanded_url": "http:\/\/twitter.com\/froginthevalley\/status\/460944092554227713\/photo\/1",
  41.         "type": "photo",
  42.         "sizes": {
  43.           "medium": {
  44.             "w": 599,
  45.             "h": 397,
  46.             "resize": "fit"
  47.           },
  48.           "thumb": {
  49.             "w": 150,
  50.             "h": 150,
  51.             "resize": "crop"
  52.           },
  53.           "small": {
  54.             "w": 340,
  55.             "h": 225,
  56.             "resize": "fit"
  57.           },
  58.           "large": {
  59.             "w": 1023,
  60.             "h": 678,
  61.             "resize": "fit"
  62.           }
  63.         }
  64.       }
  65.     ]
  66.   },
  67.   "extended_entities": {
  68.     "media": [
  69.       {
  70.         "id": 460938773744717825,
  71.         "id_str": "460938773744717825",
  72.         "indices": [
  73.           10,
  74.           32
  75.         ],
  76.         "media_url": "http:\/\/pbs.twimg.com\/media\/BmWVX2BCEAEx4MK.jpg",
  77.         "media_url_https": "https:\/\/pbs.twimg.com\/media\/BmWVX2BCEAEx4MK.jpg",
  78.         "url": "http:\/\/t.co\/fFJqqT1A4j",
  79.         "display_url": "pic.twitter.com\/fFJqqT1A4j",
  80.         "expanded_url": "http:\/\/twitter.com\/froginthevalley\/status\/460944092554227713\/photo\/1",
  81.         "type": "photo",
  82.         "sizes": {
  83.           "medium": {
  84.             "w": 599,
  85.             "h": 397,
  86.             "resize": "fit"
  87.           },
  88.           "thumb": {
  89.             "w": 150,
  90.             "h": 150,
  91.             "resize": "crop"
  92.           },
  93.           "small": {
  94.             "w": 340,
  95.             "h": 225,
  96.             "resize": "fit"
  97.           },
  98.           "large": {
  99.             "w": 1023,
  100.             "h": 678,
  101.             "resize": "fit"
  102.           }
  103.         }
  104.       },
  105.       {
  106.         "id": 460938635315916800,
  107.         "id_str": "460938635315916800",
  108.         "indices": [
  109.           10,
  110.           32
  111.         ],
  112.         "media_url": "http:\/\/pbs.twimg.com\/media\/BmWVPyVCMAAeAwI.jpg",
  113.         "media_url_https": "https:\/\/pbs.twimg.com\/media\/BmWVPyVCMAAeAwI.jpg",
  114.         "url": "http:\/\/t.co\/fFJqqT1A4j",
  115.         "display_url": "pic.twitter.com\/fFJqqT1A4j",
  116.         "expanded_url": "http:\/\/twitter.com\/froginthevalley\/status\/460944092554227713\/photo\/1",
  117.         "type": "photo",
  118.         "sizes": {
  119.           "medium": {
  120.             "w": 600,
  121.             "h": 600,
  122.             "resize": "fit"
  123.           },
  124.           "thumb": {
  125.             "w": 150,
  126.             "h": 150,
  127.             "resize": "crop"
  128.           },
  129.           "large": {
  130.             "w": 1024,
  131.             "h": 1024,
  132.             "resize": "fit"
  133.           },
  134.           "small": {
  135.             "w": 340,
  136.             "h": 340,
  137.             "resize": "fit"
  138.           }
  139.         }
  140.       }
  141.     ]
  142.   },
  143.   "favorited": false,
  144.   "retweeted": false,
  145.   "possibly_sensitive": false,
  146.   "lang": "en"
  147. }

VoilĂ ! Have fun and send us your questions at @TwitterDev.