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/3/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`

Example Request¶

GET https://ads-api.twitter.com/3/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_id": 908573900237180928,
      "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/3/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/3/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_image_url": "https://pbs.twimg.com/amplify_video_thumb/909110614026444802/img/QZUNoaiCia0UFNrw.jpg",
    "poster_image_media_key": "3_909110614026444802",
    "media_key": "13_909110614026444802",
    "created_at": "2017-09-16T17:43:55Z",
    "media_status": "TRANSCODE_COMPLETED",
    "media_id": 909110614026444802,
    "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. Attempting to use the POST accounts/:account_id/account_media endpoint with this type of video will result in an error. Videos added to the Media Library with the TWEET_VIDEO media category are not affected.

Resource URL¶

https://ads-api.twitter.com/3/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_category sometimes required	The media usecase for the specified `media_id`. Note: Required if `media_id` is specified. Type: enum Possible values: `AMPLIFY_VIDEO`, `TWEET_GIF`, `TWEET_IMAGE`, `TWEET_VIDEO`
media_id sometimes required	The `media_id` for the uploaded content. Please see either the POST `media/upload or the POST media/upload (chunked) endpoints for more information about uploading media. Note: Required if `media_key` is not specified. Type: long Example: `886374805078908930`
media_key sometimes 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. Note: Required if `media_id` is not 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_image_media_id optional	Specify a poster image for the video using the `media_id` of an uploaded image. If not specified, the first frame will be used. Note: Can only be used with videos. Type: long Example: `874132089910364232`
poster_image_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/3/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_id": 931236738554519552,
    "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/3/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_image_media_id optional	Specify a poster image for the video using the `media_id` of an uploaded image. If not specified, the first frame will be used. Note: Can only be used with videos. Type: long Example: `877783254495862574`
poster_image_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_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/3/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_image_url": "https://pbs.twimg.com/tweet_video_thumb/C7lVclqVwAQqTCZ.jpg",
    "poster_image_media_key": "3_844800354743074820",
    "media_key": "16_844800354743074820",
    "created_at": "2017-10-20T09:51:54Z",
    "media_status": "TRANSCODE_COMPLETED",
    "media_id": 844800354743074820,
    "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/3/accounts/:account_id/media_library/:media_key

Parameters¶

Name Description

account_id

required

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/3/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_image_url": "https://pbs.twimg.com/media/C_B3bTRVYAAFBFt.jpg",
    "poster_image_media_key": "3_860318839740915712",
    "media_key": "7_860318603387600896",
    "created_at": "2017-05-05T02:21:53Z",
    "media_status": "TRANSCODE_COMPLETED",
    "media_id": 860318603387600896,
    "title": "uploaded on ads.twitter.com",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-05-05T02:26:58Z",
    "deleted": true
  }
}

Creatives

Media Library¶

GET accounts/:account_id/media_library¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

GET accounts/:account_id/media_library/:media_key¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

POST accounts/:account_id/media_library¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

PUT accounts/:account_id/media_library/:media_key¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

DELETE accounts/:account_id/media_library/:media_key¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶