媒体库
简介
媒体库端点提供相关功能，可管理 Twitter 广告账号的图像、GIF 和视频。库中的媒体资产可在推文中使用并用于创建卡片。也可在多个素材中再次使用，从而无需多次上传同一资产。
API 端点
- POST media/upload 或 POST media/upload（分块）（上传媒体）
- POST accounts/:account_id/media_library（将媒体添加到媒体库）
添加到库
将媒体添加到库的过程包含两个步骤。首先，使用 POST media/upload 端点或 POST media/upload（分块）端点集来上传资产。（请参见分块媒体上传指南，获取有关多部分上传过程的详细信息。）
twurl -X POST -H upload.twitter.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media"
{
"media_id":966947208837742592,
"media_id_string":"966947208837742592",
"size":74194,
"expires_after_secs":86400,
"image":{
"image_type":"image/jpeg",
"w":800,
"h":418
}
}
然后，使用媒体 ID，通过 POST accounts/:account_id/media_library 端点将媒体添加到广告账号的媒体库。
twurl -X POST -H ads-api.twitter.com "/9/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_id=966947208837742592&name=Latte"
{
"request":{
"params":{
"name":"Latte",
"file_name":"latte.jpeg",
"media_category":"TWEET_IMAGE",
"account_id":"18ce54d4x5t",
"media_id":966947208837742592
}
},
"data":{
"tweeted":false,
"name":"Latte",
"file_name":"latte.jpeg",
"media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
"media_category":"TWEET_IMAGE",
"media_key":"3_966947208837742592",
"created_at":"2018-02-23T08:05:54Z",
"media_status":"TRANSCODE_COMPLETED",
"media_id":"966947208837742592",
"media_type":"IMAGE",
"updated_at":"2018-02-23T08:06:17Z",
"deleted":false
}
}
注意：上传后，发布图像、GIF 或视频推文也会直接将媒体添加到媒体库。
请求参数
所有媒体库 POST 请求都需要媒体标识符。在执行上传步骤过程中，系统会返回此值。如上述示例所示，当使用 media_id 时，也必须指定 media_category。可能的类别值有四个：AMPLIFY_VIDEO、TWEET_GIF、TWEET_IMAGE 和 TWEET_VIDEO。
或者，可为媒体库中的对象设置 name 和 file_name 值。这些属性可帮助用户区分库中的不同类型媒体。
对于视频，还可以设置 title 和 description。这些值旨在通过 POST accounts/:account_id/tweet 端点，作为 video_title 和 video_description 请求参数。在推文中，此文本将出现在视频下方。
属性
媒体库正式引入了 media_key 概念。这是适用于媒体库对象的唯一标识符。媒体密钥是一种字串值，格式如下：13_875943225764098048。我们的所有卡片端点均全面支持这些密钥。
此外，媒体库响应还包含 media_id（以字串表示）。此字串用于目前不接收媒体密钥的资源：推文*、推文预览*和预排期推文。我们正致力于让所有位置都支持媒体密钥。
针对 GIF 和视频，将返回 aspect_ratio 属性。此属性可用于筛选媒体，以便在仅支持特定宽高比的卡片中使用。
*这些端点支持 video_id 参数，该参数属于媒体密钥。
用法
在本部分中，以下图像将用于推文中，并且将创建网站卡片。
twurl -H ads-api.twitter.com "/9/accounts/18ce54d4x5t/media_library/3_966947208837742592"
{
"request":{
"params":{
"account_id":"18ce54d4x5t",
"media_key":"3_966947208837742592"
}
},
"data":{
"tweeted":false,
"name":"Latte",
"file_name":"latte.jpeg",
"media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
"media_category":"TWEET_IMAGE",
"media_key":"3_966947208837742592",
"created_at":"2018-02-23T08:05:54Z",
"media_status":"TRANSCODE_COMPLETED",
"media_id":"966947208837742592",
"media_type":"IMAGE",
"updated_at":"2018-02-23T08:06:17Z",
"deleted":false
}
}
推文
POST accounts/:account_id/tweet 端点暂不支持使用媒体密钥指定图像。因此，我们会使用其 media_id 来引用此图像。
twurl -X POST -H ads-api.twitter.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_ids=966947208837742592&as_user_id=756201191646691328&trim_user=true"
{
"data":{
"created_at":"Fri Feb 23 08:20:05 +0000 2018",
"id":966950781302665218,
"id_str":"966950781302665218",
"text":"coffee https://t.co/T772Hx5GNT",
"truncated":false,
"entities":{
"hashtags":[
],
"symbols":[
],
"user_mentions":[
],
"urls":[
],
"media":[
{
"id":966947208837742592,
"id_str":"966947208837742592",
"indices":[
7,
30
],
"media_url":"http://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
"media_url_https":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
"url":"https://t.co/T772Hx5GNT",
"display_url":"pic.twitter.com/T772Hx5GNT",
"expanded_url":"https://twitter.com/apimctestface/status/966950781302665218/photo/1",
"type":"photo",
"sizes":{
"thumb":{
"w":150,
"h":150,
"resize":"crop"
},
"large":{
"w":800,
"h":418,
"resize":"fit"
},
"medium":{
"w":800,
"h":418,
"resize":"fit"
},
"small":{
"w":680,
"h":355,
"resize":"fit"
}
}
}
]
},
"source":"Ads API Internal Test App",
"in_reply_to_status_id":null,
"in_reply_to_status_id_str":null,
"in_reply_to_user_id":null,
"in_reply_to_user_id_str":null,
"in_reply_to_screen_name":null,
"user":{
"id":756201191646691328,
"id_str":"756201191646691328"
},
"geo":null,
"coordinates":null,
"place":null,
"contributors":[
2417045708
],
"retweet_count":0,
"favorite_count":0,
"favorited":false,
"retweeted":false,
"possibly_sensitive":false,
"scopes":{
"followers":false
},
"lang":"en"
},
"request":{
"params":{
"as_user_id":756201191646691328,
"text":"coffee",
"account_id":"18ce54d4x5t",
"media_ids":[
966947208837742592
],
"trim_user":true
}
}
}
coffee pic.twitter.com/T772Hx5GNT
— API McTestface (@apimctestface) February 23, 2018
网站卡片
我们的所有卡片端点均支持媒体密钥。我们将通过引用图像的 media_key 来创建网站卡片。
注意：无法使用媒体库图像的 media_id 来创建卡片。
twurl -X POST -H ads-api.twitter.com "/8/accounts/18ce54d4x5t/cards/website?name=Media Library latte card&website_title=Use the Media Library&image_media_key=3_966947208837742592&website_url=/content/developer-twitter/en/docs/ads/creatives/api-reference/media-library"
{
"data":{
"name":"Media Library latte card",
"website_shortened_url":"https://t.co/mCvkfGSl5b",
"image_display_height":"418",
"image":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
"website_display_url":"developer.twitter.com",
"id":"5dkat",
"website_dest_url":"/content/developer-twitter/en/docs/ads/creatives/api-reference/media-library",
"created_at":"2018-02-23T08:25:27Z",
"image_display_width":"800",
"website_title":"Use the Media Library",
"card_uri":"card://966952130299834373",
"website_url":"/content/developer-twitter/en/docs/ads/creatives/api-reference/media-library",
"updated_at":"2018-02-23T08:25:27Z",
"deleted":false,
"card_type":"WEBSITE"
},
"request":{
"params":{
"name":"Media Library latte card",
"website_shortened_url":"https://t.co/mCvkfGSl5b",
"image_display_height":"418",
"image":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
"image_media_key":"3_966947208837742592",
"website_display_url":"developer.twitter.com",
"account_id":"18ce54d4x5t",
"website_dest_url":"/content/developer-twitter/en/docs/ads/creatives/api-reference/media-library",
"image_display_width":"800",
"website_title":"Use the Media Library",
"website_url":"/content/developer-twitter/en/docs/ads/creatives/api-reference/media-library",
"card_type":"WEBSITE"
}
}
}
然后，我们将使用卡片的 card_uri 将其与推文关联。
coffee
— API McTestface (@apimctestface) February 23, 2018