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 | None | |
| Tweet | Both |
|
| Scheduled Tweet | Both | media_ids and media_keys |
| Draft Tweet | Both | media_ids and media_keys |
| Account Media | None | |
| Media Library | Both | media_id and media_key |
Image cards and Account Media images do not include a reference any media identifier. Tweets only include media IDs. Scheduled and Draft Tweets include both the media ID and media key. The Media Library returns both, too.
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"].
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 | May be either | video_content_id |
| Video poll cards | None | |
| Tweet | Both |
|
| Scheduled Tweet | Both | media_ids and media_keys |
| Draft Tweet | Both | media_ids and media_keys |
| Account Media | Media key | video_id |
| Media Library | Both | media_id and 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 | video_url and video_hls_url |
.vmap .m3u8 |
| 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 |
Video cards include video_url and video_hls_url response attributes with .vmap and .m3u8 URLs, respectively.
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 AMPLIFY_VIDEO asset 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.