Media Library

GET accounts/:account_id/media_library

Retrieve details for some or all media library objects associated with the current account.

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/media_library

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

count
optional

Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 20
Min, Max: 1, 50
cursor
optional

Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: c-1

media_type
optional

Scope the response to just the desired media type.

Type: enum

Possible values: GIF, IMAGE, VIDEO

q
optional

An optional query to scope resource by name, title, file_name, and description fields.

Note: This performs case-insensitive term matching.

Type: string

Min, Max length: 1, 255

Example Request

GET https://ads-api.twitter.com/8/accounts/18ce54d4x5t/media_library?count=1

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "count": 1
    }
  },
  "data": [
    {
      "tweeted": true,
      "name": null,
      "file_name": "coffee https://t.co/4tcPU9XUon",
      "media_url": "https://pbs.twimg.com/media/DJvnJf_UEAAXnzC.jpg",
      "media_category": "TWEET_IMAGE",
      "media_key": "3_908573900237180928",
      "created_at": "2017-09-15T06:11:12Z",
      "media_status": "TRANSCODE_COMPLETED",
      "media_type": "IMAGE",
      "updated_at": "2017-11-16T06:00:01Z",
      "deleted": false
    }
  ],
  "next_cursor": "c-1"
}

GET accounts/:account_id/media_library/:media_key

Retrieve a specific media library object associated with the current account.

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/media_library/:media_key

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

media_key
required

A reference to the media library object you are operating with in the request.

Type: string

Example: 13_909110614026444802

Example Request

GET https://ads-api.twitter.com/8/accounts/18ce54d4x5t/media_library/13_909110614026444802

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "13_909110614026444802"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 39973,
    "name": null,
    "file_name": "buildings https://t.co/xFdzrHM5QG",
    "description": null,
    "media_url": "https://video.twimg.com/amplify_video/909110614026444802/vid/1280x720/mfahmfkKVjjk1nGm.mp4",
    "media_category": "AMPLIFY_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/909110614026444802/img/QZUNoaiCia0UFNrw.jpg",
    "poster_media_key": "3_909110614026444802",
    "media_key": "13_909110614026444802",
    "created_at": "2017-09-16T17:43:55Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "buildings",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-09-27T13:04:00Z",
    "deleted": false
  }
}

POST accounts/:account_id/media_library

Associate a media object with the current account. For additional details, please see our Media Library guide.

Note: When adding a video with the AMPLIFY_VIDEO media category to the Media Library, it is automatically available as a PREROLL account_media asset.

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/media_library

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

media_key
required

The media_key for the uploaded content. A media_key is returned in the POST media/upload response when a media_category is specified.

Type: string

Example: 3_931236738554519552

description
optional

The description that appears under the video when Tweeted. Maximum length: 200 characters.

This is not rendered in the Tweet by default. To display the video's description, use the video_description parameter with the POST accounts/:account_id/tweet endpoint.

Note: Can only be used with videos.

Type: string

Example: This is the description under the video.

file_name
optional

The file name for the media library object. Maximum length: 255.

The file name can be seen in the media detail of every media asset in the Media Library UI on ads.twitter.com. This will be empty when the file_name is not set.

Type: string

Example: coffee.jpeg

name
optional

The name for the media library object. Maximum length: 100.

This is the label under every media asset in the Media Library UI on ads.twitter.com. The label will be "Untitled" when the name is not set.

Type: string

Example: Latte

poster_media_key
optional

Specify a poster image for the video using the media_key of an uploaded image. If not specified, the first frame will be used.

Note: Can only be used with videos.

Type: string

Example: 3_890599134483242005

title
optional

The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters.

This is not rendered in the Tweet by default. To display the video's title, use the video_title parameter with the POST accounts/:account_id/tweet endpoint.

Note: Can only be used with videos.

Type: string

Example: Video title

Example Request

POST https://ads-api.twitter.com/8/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "3_931236738554519552"
    }
  },
  "data": {
    "tweeted": false,
    "name": null,
    "file_name": null,
    "media_url": "https://pbs.twimg.com/media/DOxq4TtV4AAlvh_.jpg",
    "media_category": "TWEET_IMAGE",
    "media_key": "3_931236738554519552",
    "created_at": "2017-11-16T19:05:14Z",
    "media_status": "TRANSCODE_COMPLETED",
    "media_type": "IMAGE",
    "updated_at": "2017-11-16T19:05:23Z",
    "deleted": false
  }
}

PUT accounts/:account_id/media_library/:media_key

Update the specified media library object belonging to the current account.

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/media_library/:media_key

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

media_key
required

A reference to the media library object you are operating with in the request.

Type: string

Example: 16_844800354743074820

description
optional

The description that appears under the video when Tweeted. Maximum length: 200 characters.

This is not rendered in the Tweet by default. To display the video's description, use the video_description parameter with the POST accounts/:account_id/tweet endpoint.

Note: Can only be used with videos.

Type: string

Example: This is the description under the video.

file_name
optional

The file name for the media library object. Maximum length: 255.

The file name can be seen in the media detail of every media asset in the Media Library UI on ads.twitter.com. This will be empty when the file_name is not set.

Type: string

Example: coffee.jpeg

name
optional

The name for the media library object. Maximum length: 100.

This is the label under every media asset in the Media Library UI on ads.twitter.com. The label will be "Untitled" when the name is not set.

Type: string

Example: Latte

poster_media_key
optional

Specify a poster image for the video using the media_key of an uploaded image.

Note: Can only be used with videos.

Type: string

Example: 3_885003359340375465

title
optional

The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters.

This is not rendered in the Tweet by default. To display the video's title, use the video_title parameter with the POST accounts/:account_id/tweet endpoint.

Note: Can only be used with videos.

Type: string

Example: Video title

Example Request

PUT https://ads-api.twitter.com/8/accounts/18ce54d4x5t/media_library/16_844800354743074820?title=cat GIF&description=in space

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "16_844800354743074820",
      "title": "cat GIF",
      "description": "in space"
    }
  },
  "data": {
    "tweeted": true,
    "duration": null,
    "name": null,
    "file_name": null,
    "description": "in space",
    "media_url": "https://video.twimg.com/tweet_video/C7lVclqVwAQqTCZ.mp4",
    "media_category": "TWEET_GIF",
    "poster_media_url": "https://pbs.twimg.com/tweet_video_thumb/C7lVclqVwAQqTCZ.jpg",
    "poster_media_key": "3_844800354743074820",
    "media_key": "16_844800354743074820",
    "created_at": "2017-10-20T09:51:54Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "cat GIF",
    "media_type": "GIF",
    "aspect_ratio": "125:79",
    "updated_at": "2017-10-23T06:37:56Z",
    "deleted": false
  }
}

DELETE accounts/:account_id/media_library/:media_key

Delete the specified media library object belonging to the current account.

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/media_library/:media_key

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

media_key
required

A reference to the media library object you are operating with in the request.

Type: string

Example: 7_860318603387600896

Example Request

DELETE https://ads-api.twitter.com/8/accounts/18ce54d4x5t/media_library/7_860318603387600896

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "7_860318603387600896"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 14330,
    "name": "mountains-on-ads.twitter.com",
    "file_name": "mountains.mp4",
    "description": "",
    "media_url": "https://video.twimg.com/ext_tw_video/860318603387600896/pu/vid/1280x720/xI3DbvWKxdvICsFW.mp4",
    "media_category": "TWEET_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/media/C_B3bTRVYAAFBFt.jpg",
    "poster_media_key": "3_860318839740915712",
    "media_key": "7_860318603387600896",
    "created_at": "2017-05-05T02:21:53Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "uploaded on ads.twitter.com",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-05-05T02:26:58Z",
    "deleted": true
  }
}

Was this document helpful?

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.