Adding Animated GIFs via REST and Streaming APIs

[pi_kumar]

To offer a uniform experience across Streaming and REST APIs we will be adding information about attached animated GIFs to the payloads of both. The change is scheduled to be deployed in early February on February 2nd.

Below are some examples of the differences in old and new payloads in JSON format, and what it will look like. Key things to notice in the change are:

1. Instead of url entity in “entities”, now the transcoded GIF (MP4) appears in entities and extended_entities as a media entity

2. For backwards-compatibility, the media type is still photo in “entities”, but gets a new type “animated_gif” in extended_entities

3. There is a new video_info object in extended_entities for GIF (MP4) payloads that contains the aspect ratio and the variants available

OLD:

"entities": {
        ...
        "urls": [
            {
                "url": "gif1Url",
                "expanded_url": "http://twitter.com/username/status/tweetid/photo/1",
                "display_url": "testDisplayUrl",
                "indices": [
                    1,
                    10
                ]
            }
        ],
        (media field isn't present)
    }

NEW:

"entities": {
        "hashtags": [],
        "trends": [],
        "urls": [], // <-- note this is empty
        "user_mentions": [],
        "symbols": [],
        "media": [
            {
                "id": 100,
                "id_str": "100",
                "indices": [
                    1,
                    10
                ],
                "media_url": "http://media.url.here",
                "media_url_https": "https://media.url.here",
                "url": "gif1Url",
                "display_url": "testDisplayUrl",
                "expanded_url": "http://twitter.com/username/status/tweetid/photo/1",
                "type": "photo",
                "sizes": {}
            }
        ]
    },
    "extended_entities": {
        "media": [
            {
                "id": 100,
                "id_str": "100",
                "indices": [
                    11,
                    10
                ],
                "media_url": "http://media.url.here",
                "media_url_https": "media.url.here",
                "url": "gif1Url",
                "display_url": "testDisplayUrl",
                "expanded_url": "http://twitter.com/username/status/tweetid/photo/1",
                "type": "animated_gif",
                "sizes": {},
                "video_info": {
                    "aspect_ratio": [
                        114,
                        131
                    ],
                    "variants": [
                        {
                            "bitrate": 123,
                            "content_type": "video/mp4",
                            "url": "variantUrl1"
                        },
                        {
                            "bitrate": 456,
                            "content_type": "video/mp4",
                            "url": "variantUrl2"
                        }
                    ]
                }
            }
        ]
    }

[richardhyland]

This isn’t currently in the REST API so will this be added to REST at the same time?

[richardhyland]

I do have one question. Will media_url in extended_entities be a .gif file or will it be an mp4 file url for the converted video?

[andypiper]

[andypiper]

It will be the mp4 file of the transcoded media.

[andypiper]

Clarified the announcement hope this helps.

[artesea]

Will the png poster of the mp4 be provided in the entities or should we just replace tweet_video and mp4 with tweet_video_thumb and png?

[BigZaphod]

In the “NEW” example JSON, in the “extended_entities” the media entry’s indices show [11,10] whereas in the “entities” section of the same sample, the media entry shows indices of [1,10]. I hope this is a typo in the example, because otherwise I have no idea how to make sense of it.

[BigZaphod]

I’m also unsure of how we get a poster/static image to represent the GIF/movie and would appreciate that being clarified as well!

[thegoguma]

Quick question about the aspect ratio. Will it be the reduced ratio, e.g. 1:1 or will it be expressed as width:height, e.g. 640:640?

If it’s the reduced ratio, is there a way to know the video width/height?

[andypiper]

Will the png poster of the mp4 be provided in the entities or should we just replace tweet_video and mp4 with tweet_video_thumb and png?

The media entities for animated GIF describe a static thumbnail. The idea behind this is that a media entity can always be used as a photo media entity, so that old clients that expect all media entities to be of type photo will still be able to render them. Developers should never edit URLs or assume a certain URL format is guaranteed.

In the “NEW” example JSON, in the “extended_entities” the media entry’s indices show [11,10] whereas in the “entities” section of the same sample, the media entry shows indices of [1,10]. I hope this is a typo in the example

The indices of the extended media entity are indeed incorrect sorry about that!

Quick question about the aspect ratio. Will it be the reduced ratio, e.g. 1:1 or will it be expressed as width:height, e.g. 640:640? If it’s the reduced ratio, is there a way to know the video width/height?

The aspect ratio is reduced. We currently won’t be returning the actual dimensions of the .MP4 file, but this may change in the future.

[BigZaphod]

The media entities for animated GIF describe a static thumbnail. The idea behind this is that a media entity can always be used as a photo media entity, so that old clients that expect all media entities to be of type photo will still be able to render them. Developers should never edit URLs or assume a certain URL format is guaranteed.

Ah! Okay. So the main media_url is an image. If there’s also a sizes array, then that all works just as it did for media/photos and is just different sizes of the static photo/poster image. So the video URLs are only within the video_info/variants section.

[thebryza]

I’m not clear on this: is this change only for animated gifs? or is the entities.urls ALWAYS empty when this changes in Febrary? Or just empty, if the data is an animated gif, and not another kind of image (jpg, png, whatever)?

I currently am pulling images out of entities.urls.x.expanded_urls for photos. Will this be a breaking change, as this looks empty in the “NEW” json?

[technotip]

No updates seen in the API yet
Could someone update us on this clearly?

[andypiper]

We had to change the announced date from “February 2nd” (which would be today as I type this in the UK, but is still “in the future” on PST working hours) to “early February” as we have also recently announced the video entities will be added. We’re aiming to add both sets of entities in the next week or two. Apologies for the late change to this specific announced date.

[mpowerj]

Any updates on the timeframe for this update? as of today, I am still seeing the old URL format and png image links when it comes to GIFs.

[andypiper]

That’s not expected. Can you provide any example tweet IDs that show this behaviour? this should be available in both REST and Streaming now (barring search I believe).

[mpowerj]

thanks for response @andypiper, you can disregard. I needed to educate myself on the usage of entities vs extended_entities.

[andypiper]

whew!

[Tony_Downey]

Has this been rolled out yet?