Identifying Media

Introduction

Media—images, GIFs, and videos—can be added to Tweets and cards. In addition, videos can be used as pre-roll assets and images can be promoted on the Twitter Audience Platform. This section describes how to find media references across these entities.

There are two types of media identifiers: IDs and keys. Example values for each are presented below.

Media ID Media key
1029825579531807971
13_1029825579531807971

The media key is the ID plus a numeric prefix and an underscore.

Images

The following table shows the identifier types currently available in each image-related resource's response as well as the corresponding attribute name(s).

Resource Identifier Attribute(s)
Image cards Media key media_key
Tweet Media ID entities["media"]
Scheduled Tweet Media key media_keys
Draft Tweet Media key media_keys
Account Media Media key media_key
Media Library Media key media_key

Tweets only include media IDs. Scheduled Tweets, Draft Tweets, and Media Library responses include the media key.

For Tweets, the id and id_str fields in the object within the entities["media"] array correspond to the media ID. In cases where a Tweet includes multiple images, the references to each media entity can only found in extended_entities["media"]. Note that this object is not currently rendered in the Scoped Timeline endpoint response.

In addition to references to identifiers, it's often important to have access to the image's URL.

Resource Attribute(s) Format
Image cards image .jpg
Tweet* entities["media"][0]["media_url"] or extended_entities["media"][i]["media_url"] .jpg
Scheduled Tweet None  
Draft Tweet None  
Account Media media_url .jpg
Media Library media_url .jpg

* This URL locations depend on whether the Tweet contains a single image or multiple images.

All image cards include an image response attribute that contains the Twitter image URL. (For image app download cards, the name is wide_app_image.)

For Tweets, the media URL location depends on both the type of media and the endpoint being used. For Tweets with a single image, the URL can be found in entities["media"][0]["media_url"]. This is true for both the Ads API and the Standard API. When Tweets contain multiple images, however, the URLs can only be found extended_entities["media"][i]["media_url"]. This is only available in the Standard API.

Videos

The following table shows the identifier types currently available in each video-related resource's response as well as the corresponding attribute name(s).

Resource Identifier Attribute(s)
Video cards Media key media_key
Video poll cards None  
Tweet Media ID entities["media"]
Scheduled Tweet Media key media_keys
Draft Tweet Media key media_keys
Account Media Media key media_key
Media Library Media key media_key

While video cards (with the exception of poll cards with video) include a video_content_id response attribute, there is inconsistency in the type of value returned. In some cases, it's a media ID; in others, it's a media key.

Information about how to access the video's URL is shown below.

Resource Attribute(s) Format
Video cards media_url .vmap
Tweet with video* extended_entities["media"][i]["video_info"]["variants"][j]["url"] .mp4
Scheduled Tweet None  
Draft Tweet None  
Account Media None  
Media Library media_url .mp4

* The video URL is only available through the Standard API because the Scoped Timeline endpoint does not currently return an extended_entities object.

As mentioned above, the extended_entities object is not currently rendered in the Scoped Timeline endpoint response. Because of the same reason, video URLs can only be accessed using the Standard API. Regardless of media type or the API being used, we suggest always specifying tweet_mode=extended in the request.

Media Library

It's sometimes necessary to retrieve additional information about a media asset. One use case, for video cards, is retrieving the mp4 URL instead of the vmap one. This is available in the Media Library. For details on the available information, see our Media Library Guide. Most assets belonging to the ads account's FULL promotable user can be found in the library. There are some exceptions, though.

Fetching media

As stated above, image cards do not contain references to either media IDs or media keys. As a result, it's not possible to fetch their assets through the Media Library. This is also true for Account Media images.

Video cards require that the video asset be part of the Media Library (or the Videos resource before it) prior to creating it. As a result, these assets will always be retrievable in the Media Library. This is also true for Account Media PREROLL assets.

Finally, media in Tweets are always guaranteed to be in the Media Library.

The following table summarizes which assets are retrievable in the Media Library, taking into account whether the resource response includes an identifier to use in the lookup.

Resource In the Media Library
Image cards No
Video cards Yes*
Tweets (any media)** Yes
Scheduled Tweets Yes
Draft Tweets Yes
Account media images No
Account media videos (PREROLL) Yes

* For cards where the video_content_id is a media key. When the value is a media ID, the asset still exists in the Media Library, but retrieving it involves appending a numeric prefix and underscore to it.
** Tweets only return media IDs. While the asset is guaranteed to exist in the Media Library, fetching it involves appending a numeric prefix and underscore to it.

Interactions with Account Media

There are two cases where media assets added to the library are automatically added to the Account Media resource.

  • When an asset uploaded with media_category=AMPLIFY_VIDEO is added to the Media Library, it is automatically added as an Account Media asset as a PREROLL creative type.
  • When images that have specific dimensions (see "Creative Types" in our enumerations page) are added to the Media Library, they are automatically added as Account Media assets. The creative type (e.g., INTERSTITIAL) depends on the image dimensions.