Media Library
media-library

Media Library

Run in Postman ❯ 

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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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
  }
}