メディアライブラリ
はじめに
メディアライブラリエンドポイントには、Twitter広告アカウントの画像、GIF、動画を管理する機能があります。ライブラリ内のメディアアセットをツイートで使ってカードを作ることができます。これらは複数のクリエイティブでも使用できるため、同じアセットを何度もアップロードする必要がありません。
APIエンドポイント
- POST media/uploadまたはPOST media/upload（チャンク）（メディアをアップロード）
- POST accounts/:account_id/media_library（メディアをメディアライブラリに追加）
ライブラリに追加
2つの手順でメディアをライブラリに追加できます。まず、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.x.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の指定も必要になります。可能なカテゴリー値は4つ（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などの形式の文字列値です。Twitterのすべてのカードエンドポイントで完全にサポートされています。
また、メディアライブラリ応答には文字列で表すmedia_idが含まれています。これは、現在メディアキーを受け入れていないリソース（ツイート*、ツイートプレビュー*、予約投稿ツイート）用に含まれています。Twitterはあらゆる場所でメディアキーをサポートできるよう取り組んでいます。
aspect_ratio属性はGIFと動画に対して返されます。この属性を利用して、特定のアスペクト比のみを受け入れるカードで使うメディアを絞り込むことができます。
*これらのエンドポイントは、メディアキーであるvideo_idパラメーターをサポートしています。
使用方法
このセクションでは、ツイート内で次の画像を使ってウェブサイトカードを作ります。
twurl -H ads-api.x.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.x.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
}
}
}
コーヒー pic.twitter.com/T772Hx5GNT
— API McTestface (@apimctestface) 2018年2月23日
ウェブサイトカード
すべてのカードエンドポイントでメディアキーがサポートされています。画像のmedia_keyを参照してウェブサイトカードを作ります。
注:メディアライブラリの画像のmedia_idを使ってカードを作ることはできません。
twurl -X POST -H ads-api.x.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を使って、このカードをツイートに関連付けます。
コーヒー
— API McTestface (@apimctestface) 2018年2月23日