クリエイティブ

​

概要

クリエイティブとは、キャンペーンでプロモーションできるあらゆるエンティティを指します。投稿にはテキスト、画像、GIF、動画、またはカードを含めることができます。カードには画像または動画を含めることができます。

画像、GIF、または動画クリエイティブは、POST media/upload (画像のみをサポートするシンプルなアップロードエンドポイント) または POST media/upload (chunked) エンドポイントのいずれかを使用してアップロードします。これらは次のものに追加できます。

カード:

• POST accounts/:account_id/cards ツイート:
• POST accounts/:account_id/tweets - ツイートにカードを追加するには、card_uri パラメータを使用します。 予約ツイート:
• POST accounts/:account_id/scheduled_tweets

カードの詳細については、「Cards」ページを参照してください。「Promoted Video」ページでは、動画をカードまたはツイートに関連付ける方法の詳細を確認できます。

​

カード

Ads API では、ツイートで使用でき、その後キャンペーンでプロモーションできる複数のカードタイプをサポートしています。注: 一度ツイートされると、カードの詳細は一般に公開されます。これには、そのカードの所有者であるユーザーに関する情報が含まれる場合があります。

​

画像

以下の画像仕様は、Cards で使用されるアセットに適用されます。画像は 3MB 以下で、幅が 800px 以上である必要があります。さらに、以下の幅:高さのアスペクト比をサポートしています。

• Website: 1:1 および 1.91:1
• Image App Download: 1:1 および 1.91:1
• Poll: 1.91:1
• Image Conversation: 1.91:1
• Image Direct Message: 1.91:1

サポートされている画像形式は、.bmp、.jpeg、.png です。

​

動画

以下の動画仕様は、Cards で使用されるアセットに適用されます。サポートされているアスペクト比 (横:縦) は次のとおりです。

• Video Website: 16:9 および 1:1
• Video App Download: 16:9 および 1:1
• Poll: 16:9
• Video Conversation: 16:9
• Video Direct Message: 16:9

​

プロモート動画

このドキュメントでは、Ads API を使用して動画をアップロードしてプロモーション配信する手順の概要を簡潔に説明します。

Ads API は、ツイート内および次のカードでのプロモート動画をサポートしています。

• Video Website
• Video App Download
• Video Conversation

まず、POST media/upload (chunked) エンドポイントを使って動画をアップロードします。media_id を使用して、POST accounts/:account_id/videos エンドポイントで動画を広告アカウントに関連付けます。動画の id (media_key と呼ばれることもあります) は、その後のリクエストで使用されます。これは、整数で始まり、その後にアンダースコアが続き、末尾が長い数値になる文字列です。例としては次のような形式です: 13_875943225764098048。

​

ツイート内のプロモーション動画

ツイートを作成するには、動画の id とあわせて POST accounts/:account_id/tweet エンドポイントを使用します。このステップでは、動画のタイトル、説明文、コールトゥアクション (CTA) も指定できます。これらの値はユーザーに表示されます。

​

カードでのプロモーション動画

Video App Download カードおよび Video Conversation カードでは、ポスター画像を追加できます。これらのカードで使用する画像は、POST media/upload エンドポイントを使ってアップロードします。

次のいずれかのエンドポイントを使用してカードを作成します。

• POST accounts/:account_id/cards/video_website
• POST accounts/:account_id/cards/video_app_download
• POST accounts/:account_id/cards/video_conversation

動画の id と、必要に応じて画像 (ポスター画像用) の media_id を使用します。

最後に、POST accounts/:account_id/tweet エンドポイントを使用してツイートを作成します。カードは card_uri パラメータを使ってツイートに添付されます。

​

一般情報

API を通じた動画アップロードに関する詳細な手順については、Video Upload Guide を参照してください。

動画はプレロールアセットとしてプロモーションすることもできます。詳しい説明については、Video Views Pre-roll Objective Guide を参照してください。

• (2015-10-22 時点) プロモーションで使用する動画をアップロードする場合、POST media/upload (chunked) エンドポイントへのすべての INIT コマンドリクエストで、media_category パラメータに amplify_video の値を設定する必要があります。この新しいパラメータを使用することで、動画が非同期的に事前処理され、プロモーションで利用できる状態に準備されます。動画アップロード後の非同期処理の完了状況は、STATUS コマンドを使用して確認できます。
• 現在許可されているプロモーション動画の最大長は 10 分で、ファイルサイズは 500MB 以下です。
• アップロードする動画は mp4 か mov 形式である必要があります。
• アップロードされた動画は通常は迅速に処理されますが、処理時間は動画の長さやファイルサイズによって異なる場合があります。
• アップロードするポスター画像は png または jpg 形式である必要があります。アスペクト比やサイズの要件はありませんが、ポスター画像は動画プレーヤーに合わせて調整されます。

​

ガイド

​

予約済みツイート

​

はじめに

Scheduled Tweets を使用すると、広告主やユーザーは、指定した日時に公開されるようにツイートを予約できます。これらのツイートを作成および管理できるだけでなく、API を利用することで、ツイートが公開された際にプロモーションできるよう、ツイートをラインアイテムに関連付けることも可能です。これにより、広告主はネイティブツイートをあらかじめ用意し、主要な施策に先立ってキャンペーンクリエイティブを計画できます。たとえば、新製品発表と同時に公開されるようにツイートクリエイティブを事前にステージングしておく、といった使い方が可能です。

Scheduled Tweets API エンドポイントが提供する機能は次のとおりです。

• 新規の予約ツイートを作成、変更、閲覧する
• 予約ツイートをラインアイテムに関連付ける
• 既存の予約ツイートを検索および管理する
• 予約ツイートが公開されたら、公開済みツイートの id を取得する

​

API エンドポイント

上記の機能に関連するすべてのエンドポイントは、以下のとおりです。

​

予約ツイートの管理

• GET accounts/:account_id/scheduled_tweets (すべての予約ツイートの一覧を取得)
• GET accounts/:account_id/scheduled_tweets/:scheduled_tweet_id (id を使用して特定の予約ツイートを取得)
• POST accounts/:account_id/scheduled_tweets (新しい予約ツイートを作成)
• PUT accounts/:account_id/scheduled_tweets/:scheduled_tweet_id (既存の予約ツイートを更新)
• DELETE accounts/:account_id/scheduled_tweets/:scheduled_tweet_id (id を使用して予約ツイートを削除)
• GET accounts/:account_id/scheduled_tweets/preview/:scheduled_tweet_id (既存の予約ツイートをプレビュー表示)

​

予約済みプロモーションツイート

• GET accounts/:account_id/scheduled_promoted_tweets (すべての予約済みプロモーションツイートのリストを取得します)
• GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id (id を使用して予約済みプロモーションツイートを取得します)
• POST accounts/:account_id/scheduled_promoted_tweets (新しい予約済みプロモーションツイートを作成します)
• DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id (id を使用して既存の予約済みプロモーションツイートを削除します)

​

予約ツイートの閲覧

• GET accounts/:account_id/scheduled_tweets/preview/:scheduled_tweet_id (既存の予約ツイートを閲覧)

予約ツイートは「ライブ」のツイートとは別個のエンティティであるという性質上、これらのツイートを新規作成または編集する際には、2 種類の異なる検証処理が実行されます。最初の検証ルールセットは、予約ツイートの作成ステップで実行されます。

​

Scheduled Tweet Create:

• 認証済みユーザーが、指定された @handle に対してオーガニックツイートを作成するアクセス権を持っているか検証します。Promoted-Only ツイートの作成権限には、認証済みユーザーが Tweet composer permissions を持つアカウントユーザーである必要があります。
• scheduled_at 時刻の前後 15 分間のウィンドウ内で作成が予定されているツイートが 30 件を超えていないか検証します。SCHEDULED_TWEET_LIMIT_EXCEEDED エラーメッセージは、同じ将来の 15 分間の時間枠内に、予約ツイートが多すぎることを示します。広告主は、既存の予約ツイートを削除するか、scheduled_at の時刻を前または後ろにずらす必要があります。

​

予約ツイートが「公開」されるとき:

• これらのバリデーションルールは scheduled_at に設定された時刻に実行され、API で通常のツイートを作成する際に適用されるものと同一です。たとえば、予約ツイートに画像と GIF の両方が含まれている場合、その予約ツイートは公開されず、scheduled_status は FAILED に設定されます。

​

ワークフロー

新しい予約ツイートを作成する

新しい予約ツイートは、POST accounts/:account_id/scheduled_tweets エンドポイントを使用して作成できます。このエンドポイントには必須パラメーターとして、scheduled_at の時刻と、ツイートにメディアエンティティが含まれない場合のツイート text が必要です。さらに、このエンドポイントでは、as_user_id パラメーターを使って別の @handle の代わりに予約ツイートを作成したり、カード (card_uri) やメディア (media_ids) を追加したりできる、いくつかの追加オプションも用意されています。なお、1つのツイートに含められるエンティティは同じ type のもののみで、Video、Gif、Image のいずれか1種類だけです。nullcast パラメーターは、そのツイートが「プロモーション専用」ツイートかどうかを制御します。新しく作成されるすべての予約ツイートは、デフォルトで「Promoted-Only」 (nullcast=true) です。nullcast=false の場合は、オーガニック予約ツイートが作成されます。

予約ツイートが正常に作成されると、レスポンスには、その予約ツイート自体の一意の識別子を表す id フィールドが含まれます。このフィールドに加えて、tweet_id という別のフィールドも返されます。このフィールドは当初 null ですが、ツイートが投稿されると、このフィールドには「ライブ」ツイートの ID が設定されます。

twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_tweets" -d 'scheduled_at=2017-12-24T23:59:00Z&text=Happy Holidays!'

これにより、次のような予約ツイートが作成されます。

{
  "request": {
    "params": {
      "text": "Happy Holidays!",
      "scheduled_at": "2017-12-24T23:59:00Z"
    }
  },
  "data": {
    "completed_at": null,
    "id_str": "917507899668099072",
    "text": "Happy Holidays!",
    "user_id": "3271358660",
    "scheduled_status": "SCHEDULED",
    "id": 917507899668099100,
    "nullcast": true,
    "created_at": "2017-10-09T21:51:44Z",
    "scheduled_at": "2017-12-24T23:59:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T21:51:44Z",
    "tweet_id": null,
    "media_keys": []
  }
}

この予約ツイートが公開されると、tweet_id フィールドには実際に公開されるツイートの ID が設定されます。

予約ツイートを表示する

GET accounts/:account_id/tweet_previews エンドポイントを、前のステップで取得した予約ツイートの id と組み合わせて使用することで、ツイートのプレビューを生成できます。API レスポンスには、予約ツイートのプレビューをレンダリングするためにそのまま使用できる iframe の URL が含まれます。関連する CSS と画像は、X から直接配信されます。

twurl -H ads-api.x.com -X GET "/6/accounts/18ce54bgxky/tweet_previews?tweet_type=SCHEDULED&tweet_ids=917507899668099072

{
  "request": {
    "params": {
      "tweet_type": "SCHEDULED",
      "tweet_ids": [
        "917507899668099072"
      ],
      "account_id": "18ce54bgxky"
    }
  },
  "data": [
    {
      "tweet_id": "1126633863155871744",
      "preview": "<\iframe class='tweet-preview' src='https://ton.smf1.x.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAK1WTW%2FjNhD9Kyyv9dqSZdmOgALJbhJsCyxaIDkUWBUEJY0lNhSpklRSN%2FV%2F71CyZbm297S%2BWJxPzpt5I71T9wbgaELeaW6AOygYxyN9rlryhW9JcEPmUbKIkuiG%2FBjgj8yD8IZOqChoEobz5TKK1ssojOP1KlwtFl7BrDMY4oIW%2FTatlMzB3z7JZ940W%2FJZS1Hwrf0Btc60Kve3oMmGSwsTWgjbSL7tXJjhqgSafA0mYfzHhIJywgmwNHmnFbeV4yU%2Bf0WN3daZlvtDa8Gw2htrdRCZXrlDU92aHIPStA2CKOekMrD5KaWVc02SztIZps%2Bh0rIAg27TXNcpJQYk2ii90VLqt7R3ht%2B4cQoMeVClUIAPd03Th01nvDfx0ClmoJFYk0aouGst82gqROaKskf03KCr7LLvXnXN02K3QTHFaziovYdH0seL5qswitfLZTBq6FGIRfSe9Lm1FTfkY%2BX%2FFcpPAlNRC7eufdFSY1%2BxASh84oo8YitzYXM9IZ%2FuaNcQ1HjMbQc61l0VXDmYlsJVbTYVGq0KwPCi2cf5tQFFnjR2zyDU6YycwX%2Fr3oRzvfKpwTaSZ8NfQUoU%2FUsetanxAV79VElhHbm1oIrSiILcvvgquqSN0Q7y8Uz2TQdjWa5bhZP8IUShEeh8IvIxkVB7SY%2FyKctaIL%2B0kgQrMp8n0SKJ10eWxZ4t%2FBXHUzg4idu6nOnNxsIQ1Yka2D9aDc0sQTNQPJP%2B2sgqvPUrGLERozL68ToNLRELvBj4VuZaOSOy1mmsdAi2dxaWOeyhlRzVl6TYozMnhHIjJLCM5y%2BlwaweHOn96afg%2FuHhnl60ETUvgR1HpJsQntkptrcuO0bOOhuLg1NBPfyH6Swrpw2W9O24rBu8kwH8DuEdns9Kv1hLc5rsxBaTLcN1HIdhHIVRuFov5wtMXH748vO2%2BP0jUzjFXE7%2FbMa3%2BFZl3z1ZxhWyjv2fwlfy9NaY6LhO0lm4WC3WcRSvlqO4UqiXYT7C%2B7vwcT7SWlFAxg3LtMHNfH2ODnZ4kIPVPRo9jnN1r5eDNup%2BIy2y5GxuDrQqYMNb6dje9or44HOyQYTnWs%2FXXoD7%2Ba8WrGO4hwZuK%2B2Qt%2F32tAPhB%2B4xt238qjVQtpIbuuvIP6wbjfAIhStncO3eZ0f9keMHmYHuo%2BCwFoJ%2BDfktdEF0JPfebbxgct30b%2BdhY%2B51u%2FGm2U2IR7rW%2FbJU%2FdcBfpEchHjwoO52%2FwENmVvErwgAAA%3D%3D'>"
    }
  ]
}

新しく作成された予約ツイートのサンプル画面が上に表示されています

予約ツイートをラインアイテムに関連付ける

予約ツイートはオーガニックツイートの作成に利用できますが、パートナーは「Promoted-Only」 (nullcast=true) のツイートも作成でき、いずれもラインアイテムに関連付けることができます。このために、POST accounts/:account_id/scheduled_promoted_tweets エンドポイントも提供しています。このエンドポイントでは、1 回の API 呼び出しで 1 件のプロモーション用予約ツイートのみを 1 つのラインアイテムに関連付けることができます。同じラインアイテムに複数の予約ツイートを関連付けるには、複数回の API 呼び出しが必要です。

既存のプロモーション用予約ツイートを変更することはできない点にご注意ください。

twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_promoted_tweets" -d 'line_item_id=a44qc&scheduled_tweet_id=917507899668099072'

{
  "data": {
    "line_item_id": "a44qc",
    "id": "26576",
    "created_at": "2017-10-09T22:24:16Z",
    "updated_at": "2017-10-09T22:24:16Z",
    "scheduled_tweet_id": "917507899668099072",
    "tweet_id": null,
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "a44qc",
      "scheduled_tweet_id": 917507899668099100,
      "account_id": "aaaaa"
    }
  }
}

このエンドポイントは、指定された予約ツイートとラインアイテムの関連付けを作成するだけです。キャンペーン／ラインアイテムのフライト期間が現在を含むようになると、そのラインアイテムは対応する「ライブ」ツイートの配信を自動的に開始します。このステップでは、予約ツイートが SCHEDULED 状態にあること、および指定された予約ツイートが指定の objective に対して有効であることは検証しますが、それ以外の検証処理は実行されません。ラインアイテムと予約ツイートに適用される残りの検証ルールは、ツイートが「ライブ」になるタイミングで実行されます。

キャンペーン配信に問題が発生しないようにするため、予約ツイートの scheduled_at を、キャンペーン／ラインアイテムのフライト期間よりも前の時刻に設定することを推奨します。

たとえば、予約ツイートがキャンペーン開始日より後にライブになるように設定されているとします (かつ、単一のラインアイテムに単一のツイートのみが関連付けられている場合) 。この場合、キャンペーンは ACTIVE の状態になりますが、予約ツイートはまだライブになっていないため、配信可能なクリエイティブが存在しない状態になります。

予約ツイート管理

残りのエンドポイント群により、API 利用者はすべての予約ツイートおよび予約プロモツイートを管理できます。これらの API を使用すると、すべての予約ツイートを、任意で指定された状態でフィルタリングしたリストとして取得したり、id によって特定の予約ツイートをルックアップしたりできます。

​

スケジュール済みツイートが公開されると何が起こりますか？

あるスケジュール済みツイートが公開されるタイミング、つまり scheduled_at の時刻になると、次の更新が行われます。

• 「ライブ」のツイートが作成されますが、最大 1 秒程度の遅延が発生する場合があります
• tweet_id が次のエンティティに追加されます:
• スケジュール済みツイート
• プロモーション用スケジュール済みツイート
• 新しいプロモーション用ツイートエンティティが作成されます

​

ベストプラクティス

予約ツイートを作成またはプロモーション配信する際には、次のベストプラクティスに従うことを推奨します。

• 予約ツイートを作成する際、ツイートが有効であることを確認してください (たとえば、1 つのツイートには画像・動画・GIF のいずれか 1 種類のみを含めることができ、複数種類を組み合わせることはできません)
• キャンペーンのフライト期間 (start_time と end_time) が、予約ツイートの scheduled_at の時刻と整合していることを確認してください
• 予約ツイートは、現在から 1 年 (365 日) を超える未来の日時にはスケジュールしないでください
• 現在、予約ツイートに対するツイートのプレビュー機能はサポートされていません (作成前に予約ツイートをプレビューする機能を指します)

​

メディアライブラリ

​

概要

Media Library エンドポイントを使用すると、X Ads アカウントの画像、GIF、動画を管理できます。ライブラリ内のメディアアセットは、ツイートに利用したりカードを作成したりできます。また、同じアセットを複数のクリエイティブで再利用できるため、同一のアセットを何度もアップロードし直す必要がありません。

​

API エンドポイント

• POST media/upload (メディアをアップロードする) またはPOST media/upload (chunked) (メディアをアップロードする (チャンク) )
• POST accounts/:account_id/media_library (Media Library にメディアを追加する)

​

ライブラリへの追加

メディアをライブラリに追加するには、2段階の処理が必要です。まず、POST media/upload エンドポイント、または POST media/upload (chunked) エンドポイント群のいずれかを使ってアセットをアップロードします (マルチパートアップロード処理の詳細については、Chunked media upload ガイドを参照してください) 。

twurl -X POST -H upload.x.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_key=966947208837742592&name=Latte"

{
   "request":{
      "params":{
         "name":"Latte",
         "file_name":"latte.jpeg",
         "media_category":"TWEET_IMAGE",
         "account_id":"18ce54d4x5t",
         "media_key":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_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

注: アップロード直後に画像、GIF、動画をツイートすると、そのメディアもメディアライブラリに追加されます。

​

リクエストパラメータ

すべての Media Library の POST リクエストにはメディア識別子が必要です。この値はアップロード時に返されます。上記の例のように media_id を使用する場合、media_category も指定する必要があります。カテゴリーとして指定できる値は、AMPLIFY_VIDEO、TWEET_GIF、TWEET_IMAGE、TWEET_VIDEO の 4 種類です。

任意で、Media Library 内のオブジェクトに対して name と file_name の値を設定できます。これらの属性は、ライブラリ内でメディアのバリアントを区別するのに役立ちます。

動画の場合は、title と説明文を設定することもできます。これらの値は、POST accounts/:account_id/tweet エンドポイントで、video_title および video_description リクエストパラメータとして渡すことを想定しています。ツイートでは、このテキストが動画の下に表示されます。

​

属性

Media Library では、media_key という概念が正式に導入されています。これは、ライブラリ内のオブジェクトを一意に識別するための識別子です。media_key は、13_875943225764098048 のような形式の文字列です。これらは、すべてのカードエンドポイントで完全にサポートされています。

加えて、Media Library レスポンスには、文字列として表現される media_id も含まれます。これは、現時点では media_key を受け付けていないリソース、つまり ツイート、ツイートプレビュー、および 予約ツイート に対して返されます。現在、すべての場所で media_key がサポートされるよう取り組んでいます。

aspect_ratio 属性は GIF と動画に対して返されます。これは、特定のアスペクト比のみを受け付けるカードで使用するメディアをフィルタリングするために利用できます。

*これらのエンドポイントでは、media_key である 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_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

ツイート

画像を media_keys で指定してツイートを作成できます。

twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=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.x.com/T772Hx5GNT",
               "expanded_url":"https://x.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_keys":[
            966947208837742592
         ],
         "trim_user":true
      }
   }
}

ウェブサイトカード

すべてのカードエンドポイントは media_key をサポートしています。画像の media_key を指定してウェブサイトカードを作成します。

twurl -X POST -H ads-api.x.com "/11/accounts/18ce54d4x5t/cards"

{
  "name": "components create cards",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1323490622599176192"
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android"
      }
    }
  ]
}

次に、このカードを card_uri を使用してツイートに関連付けます。

​

カードの特定

​

はじめに

Cards はメディアを使用するカスタマイズ可能な広告フォーマットで、Web サイト、App、または特定のユーザーエンゲージメント (ダイレクトメッセージの開始など) を促すコールトゥアクションに関連付けることができます。Cards はツイート、予約ツイート、下書きツイートに添付できます。

Cards は、ツイートオブジェクト内で 2 通りの方法で参照できます。card の card_uri による方法と、preview_url による方法です。それぞれの例となる値を以下に示します。

card_uri	preview_url
card://1043282691834048513	https://cards.x.com/cards/18ce54d4x5t/68w3s

注記: Ads API バージョン 3 以降、新しく作成された card に対しては、cards レスポンスで card_uri のみが生成されて返されます。

注記: Ads API バージョン 5 以降、cards レスポンスでは preview_url は返されなくなりました。

ツイートオブジェクトのレスポンスにおける参照の種類は、そのツイートがどのように作成されたかによって異なります。つまり、ツイートが card_uri リクエストパラメータを使用して作成された場合は、その card URI の値がレスポンスに含まれます。一方で、preview_url がツイート本文の一部として含まれていた場合は、その preview URL がレスポンスに含まれます。

​

card_uri を使用したツイートの識別

card の URI 値を使用して作成されたツイートの場合は、レスポンスの card_uri 属性内にある card への参照を探します。以下のレスポンス例では、GET accounts/:account_id/tweets エンドポイントを使用しています。

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168"
{
  "request": {
    "params": {
      "tweet_ids": [
        "1043551275923591168"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "source": "Ads API Internal Test App",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        15
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1043551275923591168",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 1043551275923591168,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Sat Sep 22 17:23:07 +0000 2018",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "card_uri": "card://1043282691834048513",
      "full_text": "Tracking a card",
      "lang": "en",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1043551275923591168"
    }
  ]
}

Standard API を利用する場合は、リクエストに include_card_uri=true パラメータを付与してください。

どのエンドポイントを使用している場合でも、そのツイートが Card URI を使って作成されている場合にのみ、レスポンス属性 card_uri が返されます。

予約投稿および下書きのツイートオブジェクトでは、レスポンスには常にレスポンス属性 card_uri が含まれます。

​

preview_url でツイートを識別する

ツイートのテキストの一部として preview URL を含めて作成されたツイートでは、URL は entities[“urls”][i][“expanded_url”] に格納されます (text フィールドには短縮された t.co URL が含まれます) 。ここで i は配列インデックスです (1 つのツイートには複数の URL を含めることができます) 。

予約投稿および下書きの Tweet オブジェクトでは、preview URL は常に text フィールドに含まれます。

​

カードの取得

特定のカードに関する追加情報を取得するには、2つのエンドポイントがあります。GET accounts/:account_id/cards/all と GET accounts/:account_id/cards/all/:card_id です。前者は card_uri を指定してカードを取得し、後者はカードの ID を指定してカードを取得します。カードの ID は preview_url の末尾にあります。上記の例では、ID は 68w3s です。

​

メディアの特定

​

はじめに

メディア (画像、GIF、動画) はツイートやカードに追加できます。さらに、動画はプレロール用アセットとして、画像は X Audience Platform 上でプロモーションに利用できます。このセクションでは、これらのエンティティにわたってメディアの参照を特定する方法について説明します。

メディア識別子には 2 種類あります。ID とキーです。各種の例は以下のとおりです。

メディアID	メディアキー
1029825579531807971	13_1029825579531807971

メディアキーは、ID に数値プレフィックスとアンダースコアを付けたものです。

​

画像

次の表は、各画像関連リソースのレスポンスで現在利用可能な識別子の種類と、それに対応する属性名を示しています。

Resource	Identifier	Attribute(s)
Image cards	None
Tweet	Both	entities["media"]["id_str"] entities["media"]["media_key"]
Scheduled Tweet	Both	media_ids and media_keys
Draft Tweet	Both	media_ids and media_keys
Account Media	None
Media Library	Both	media_id and media_key

Image cards と Account Media の画像には、メディア識別子への参照は含まれません。Tweet にはメディア ID のみが含まれます。Scheduled Tweet と Draft Tweet にはメディア ID とメディアキーの両方が含まれます。Media Library も同様に両方を返します。

Tweet の場合、entities[“media”] 配列内のオブジェクトにある id と id_str フィールドがメディア ID に対応します。1 つの Tweet に複数の画像が含まれる場合、それぞれのメディアエンティティへの参照は extended_entities[“media”] にのみ存在します。

識別子への参照に加えて、画像の URL にアクセスできることも重要な場合がよくあります。

Resource	Attribute(s)	Format
Image cards	image	.jpg
Tweet*	entities["media"][0]["media_url"] または extended_entities["media"][i]["media_url"]	.jpg
Scheduled Tweet	None
Draft Tweet	None
Account Media	media_url	.jpg
Media Library	media_url	.jpg

• この URL の位置は、Tweet に 1 つの画像が含まれるか複数の画像が含まれるかによって異なります。

すべての Image cards には、X の画像 URL を含む image レスポンス属性が存在します (image app download card の場合、この属性名は wide_app_image です) 。

Tweet の場合、メディア URL の位置は、メディアの種類と使用しているエンドポイントの両方に依存します。画像が 1 枚だけ含まれる Tweet の場合、URL は entities[“media”][0][“media_url”] にあります。これは Ads API と Standard API の両方で同じです。一方、Tweet に複数の画像が含まれる場合、URL は extended_entities[“media”][i][“media_url”] にのみ存在します。これは Standard API でのみ利用可能です。

​

動画

次の表は、各動画関連リソースのレスポンスで現在利用可能な識別子の種類と、それに対応する属性名を示しています。

Resource	Identifier	Attribute(s)
Video cards	いずれか一方	video_content_id
Video poll cards	なし
Tweet	両方	entities["media"]["id_str"] entities["media"]["media_key"]
Scheduled Tweet	両方	media_ids および media_keys
Draft Tweet	両方	media_ids および media_keys
Account Media	メディアキー	video_id
Media Library	両方	media_id および media_key

Video cards (動画付きの poll cards を除く) には video_content_id レスポンス属性が含まれますが、返される値の種類に一貫性がありません。メディア ID の場合もあれば、メディアキーの場合もあります。

動画の URL を取得する方法に関する情報を以下に示します。

Resource	Attribute(s)	Format
Video cards	video_url および video_hls_url	.vmap .m3u8
Tweet with video	extended_entities["media"][i]["video_info"]["variants"][j]["url"]	.mp4
Scheduled Tweet	なし
Draft Tweet	なし
Account Media	なし
Media Library	media_url	.mp4

Video cards には、.vmap および .m3u8 の URL を持つ video_url と video_hls_url レスポンス属性が含まれます。

​

メディアライブラリ

メディアアセットに関する追加情報を取得する必要がある場合があります。ユースケースの 1 つとして、動画カードで vmap URL ではなく mp4 URL を取得したい場合が挙げられます。これはメディアライブラリで利用できます。利用可能な情報の詳細については、Media Library Guide を参照してください。広告アカウントの FULL プロモーション可能ユーザーに属するほとんどのアセットは、このライブラリで見つかりますが、いくつか例外もあります。

メディアの取得

前述のとおり、画像カードには media ID または media key への参照が含まれていません。その結果、メディアライブラリを通じてこれらのアセットを取得することはできません。これは Account Media の画像についても同様です。

動画カードは、作成前に動画アセットがメディアライブラリ (またはその前身である Videos リソース) の一部である必要があります。その結果、これらのアセットは常にメディアライブラリから取得可能です。これは Account Media の PREROLL アセットにも当てはまります。

最後に、ツイート内のメディアは常にメディアライブラリに存在することが保証されています。

次の表は、どのアセットがメディアライブラリから取得可能かを、ルックアップに使用する識別子をリソースのレスポンスが含んでいるかどうかを考慮してまとめたものです。

Resource	メディアライブラリに存在するか
画像カード	No
動画カード	Yes*
ツイート (任意のメディア) **	Yes
予約ツイート	Yes
下書きツイート	Yes
Account Media 画像	No
Account Media 動画 (PREROLL)	Yes

• video_content_id が media key であるカードの場合。値が media ID である場合でもアセットはメディアライブラリに存在しますが、取得するには、先頭に数値のプレフィックスとアンダースコアを付与する必要があります。
  ** ツイートは media ID のみを返します。アセットがメディアライブラリに存在することは保証されていますが、取得するには、先頭に数値のプレフィックスとアンダースコアを付与する必要があります。

Account Media との連携

ライブラリに追加されたメディアアセットが自動的に Account Media リソースにも追加されるケースが 2 つあります。

• AMPLIFY_VIDEO アセットがメディアライブラリに追加されると、自動的に Account Media アセットとして、PREROLL クリエイティブタイプで追加されます。
• 特定の寸法 (enumerations ページ の “Creative Types” を参照) を持つ画像がメディアライブラリに追加されると、自動的に Account Media アセットとして追加されます。クリエイティブタイプ (例: INTERSTITIAL) は画像の寸法によって決まります。

​

ツイート

​

はじめに

X Ads API は、公開済み、予約済み、下書きの 3 種類のツイートをサポートしています。

​

ノルキャストされたツイート

ツイートはノルキャスト (別名「Promoted-only」) かオーガニックのいずれかになります。ノルキャストされたツイートは、公開されてもユーザーの公開タイムラインには表示されませんが、公開状態であることに変わりはありません。一方、オーガニックツイートはユーザーのフォロワーに配信され、ユーザーの公開タイムラインにも表示されます。

ツイートの作成

3 つのツイート作成エンドポイントそれぞれは、ツイートをノルキャストにするかオーガニックにするかを選択できるブール値の nullcast パラメーターをサポートしています。ノルキャストされたツイートは、そのユーザー本人か、ユーザーの代理としてツイートを作成する権限を持つユーザーであれば作成できます。オーガニックツイートを作成できるのは、フルプロモーション可能ユーザー のみです。

ツイートの更新

予約済みツイートおよび下書きツイートについては、nullcast プロパティを更新できます。予約済みツイートは、そのツイートの scheduled_at 時刻まで編集可能です。下書きツイートは無期限に編集できます。ただし、一度公開されると、そのツイートをノルキャストからオーガニックへ、またはその逆に変更することはできません。

​

プロモーションするツイート

プロモーションできるのは、公開済みツイートと予約ツイートのみです。これらはノルキャストでもオーガニックでもかまいません。広告主は、自分のツイートだけでなく、許可を得ている限り他のユーザーのツイートもプロモーションできます。 (詳細は「他のユーザーのツイートをプロモーションする」を参照してください。)

1 つのキャンペーンで複数のツイートをプロモーションすることができます。同様に、1 つのツイートを 1 つ以上のキャンペーンでプロモーションすることもできます。

公開済みツイートをプロモーションするには、POST accounts/:account_id/promoted_tweets エンドポイントを使用します。これにより、公開済みツイートがラインアイテムに関連付けられます。予約ツイートをプロモーションするには、POST accounts/:account_id/scheduled_promoted_tweets エンドポイントを使用します。

​

ツイートID

公開済み、予約済み、および下書きのツイートIDは数値であり、64ビットの符号なし整数です。たとえば、次の公開済みツイートのIDは 1166476031668015104 です。

公開済みまたは予約済みツイートをプロモーションすると、対応するプロモーションツイートエンティティが作成されます。これらのエンティティには独自のIDがあり、英数字から成る base-36 でエンコードされた値として表されます。たとえば、上記の公開済みツイートを、つまりラインアイテム 6c62d に関連付けてプロモーションすると、次の API レスポンスが返されます。

$ twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/promoted_tweets?line_item_id=6c62d&tweet_ids=1166476031668015104"
{
  "request": {
    "params": {
      "tweet_ids": [
        1166476031668015104
      ],
      "line_item_id": "6c62d",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "line_item_id": "6c62d",
      "id": "3qwlq6",
      "entity_status": "ACTIVE",
      "created_at": "2019-09-12T21:39:10Z",
      "updated_at": "2019-09-12T21:39:10Z",
      "approval_status": "ACCEPTED",
      "tweet_id": "1166476031668015104",
      "deleted": false
    }
  ],
  "total_count": 1
}

作成リクエストに渡されたツイートIDとラインアイテムIDに加えて、レスポンスには、値が 3qw1q6 の id フィールドが含まれており、これはプロモーションツイートのIDです。

​

カルーセル

​

はじめに

X Ads API では、動画カルーセルおよび画像カルーセルの作成と取得をサポートしています。カルーセルは、2〜6 個のメディアアセットを含めることができるカードの一種です。カルーセルカードは、ユーザーをウェブサイトへ誘導したり、モバイルアプリのインストールを促したりできます。カルーセルの概要、その利点、ベストプラクティス、FAQ については、「Carousel Ads on X」ページをご覧ください。

カルーセルは、他のカードと同様にツイート内で使用でき、それらのツイートをプロモーション配信できます。ワークフローは、すでに慣れ親しんでいるものと同じです。

1. メディアをアップロードする
2. カードを作成する
3. ツイートを作成する
4. ツイートをプロモーション配信する

唯一の違いはカードの作成方法です。他のカード作成リクエストがクエリパラメータを受け付けるのに対し、カルーセルカード作成リクエストは JSON 形式の POST ボディのみを受け付けます。

​

エンドポイント

Ads API では、カルーセルの作成および取得が可能です。

任意の種類のカルーセルを作成するには、POST accounts/:account_id/cards エンドポイントを使用します。カルーセルを取得するには、GET accounts/:account_id/cards エンドポイントを使用します。

​

JSON POST 本文

カルーセルは 2 つのコンポーネントを使用して作成されます。1 つ目は使用するメディアアセットを指定し、2 つ目はウェブサイトまたはアプリのいずれかに関する情報を指定します。

具体的には、カルーセルカードは次のコンポーネントをこの順序で使用して作成します。

• SWIPEABLE_MEDIA コンポーネントを 1 つ — メディアキーの配列を受け取ります
• いずれか 1 つ を次から選択:
• ウェブサイト情報を指定するための DETAILS コンポーネント
• アプリ情報を指定するための BUTTON コンポーネント

SWIPEABLE_MEDIA コンポーネントには、2 ～ 6 個の画像または動画を指定できる media_keys 配列を含める必要があります。渡されたメディアキーの順序によって、表示される順序が決まります。

{
  "type": "SWIPEABLE_MEDIA",
  "media_keys": [
    "13_1089771253848666112",
    "13_1191948012077092867"
  ]
}

念のため、GET accounts/:account_id/media_library エンドポイントにリクエストを送信することで、メディアキーを取得できます。

2 番目のコンポーネントオブジェクトの構成は、ユーザーをウェブサイトに誘導したいのか、App のインストールを促したいのかによって異なります。以下の表に、この 2 つのオプションをまとめます。 (注: 記載されているキーはすべて必須です。)

	ウェブサイト	App
コンポーネント type の指定	"type": "DETAILS"	"type": "BUTTON"
タイトル/ラベル	"title": "X"	"label": { "type": "ENUM", "value": "INSTALL" }
遷移先	"destination": { "type": "WEBSITE", "url": "https://www.x.com" }	"destination": { "type": "APP", ... }

これらを組み合わせると、ウェブサイトカルーセル向けの JSON POST リクエストボディの例は次のようになります。

{
  "name": "website carousel",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "DETAILS",
      "title": "X",
      "destination": {
        "type": "WEBSITE",
        "url": "https://www.x.com"
      }
    }
  ]
}

BUTTON コンポーネント内の App 宛先オブジェクトには、国コードと少なくとも 1 つのアプリ識別子が必要です。オプションとしてディープリンクを指定できます。これらのフィールドの説明については、リファレンスドキュメントを参照してください。

以上を踏まえたアプリカルーセルの JSON POST リクエストボディの例を、以下に示します。

{
  "name": "app carousel",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android",
        "iphone_app_id": "333903271"
      }
    }
  ]
}

​

例

このセクションでは、動画ウェブサイトカルーセルカードの作成方法と、それをツイートで使用する方法を示します。前述のとおり、ワークフローは、メディアをアップロードし、カードを作成し、ツイートを作成するという、これまで慣れ親しんだ流れと同じです。異なるのはカードの作成方法だけです。

メディア

まず、新しいメディアアセットをアップロードするか、既存のものを使用します。新しいメディアアセットのアップロード方法および Media Library への追加方法の詳細については、Media Library ガイドを参照してください。

メディアアセットが Media Library に追加されたら、GET accounts/:account_id/media_library エンドポイントを使用して取得します。media_type リクエストパラメータを使用して、結果を特定のメディアタイプに絞り込みます。

$ twurl -H ads-api.x.com "/10/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_type": "VIDEO"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "tweeted": true,
      "duration": 5283,
      "name": "Sunrise",
      "file_name": "sunrise.mp4",
      "description": null,
      "media_url": "https://video.twimg.com/amplify_video/1089771253848666112/vid/1280x720/tyL-pUBP7GgkS9bl.mp4?tag=9",
      "poster_media_key": "3_1089771253848666112",
      "media_key": "13_1089771253848666112",
      "created_at": "2019-01-28T06:24:48Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1089771253848666112/img/WOYvToSRZFXUSDzd.jpg",
      "title": null,
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2019-08-23T19:05:33Z",
      "deleted": false
    },
    {
      "tweeted": true,
      "duration": 15248,
      "name": "snow",
      "file_name": "snow.mp4",
      "description": "Two, three, and to the four",
      "media_url": "https://video.twimg.com/amplify_video/1191948012077092867/vid/1280x720/2cOvadcctqqea6Hx.mp4?tag=13",
      "poster_media_key": "3_1191948012077092867",
      "media_key": "13_1191948012077092867",
      "created_at": "2019-11-06T05:18:46Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1191948012077092867/img/IUbhTRd62SEeIVTf.jpg",
      "title": "One",
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2020-03-27T22:23:18Z",
      "deleted": false
    }
  ]
}

カルーセルの作成

カルーセルを作成するには、POST accounts/:account_id/cards エンドポイントを使用します。前のリクエストで取得したメディアキーを使用してください。メディアキーを渡す順序によって、表示される順序が決まることに注意してください。

$ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/10/accounts/18ce54d4x5t/cards" -d '{"name":"website carousel","components":[{"type": "SWIPEABLE_MEDIA","media_keys":["13_1089771253848666112","13_1191948012077092867"]},{"type": "DETAILS","title": "X","destination":{"type":"WEBSITE", "url":"https://www.x.com"}}]}'

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "website carousel",
    "components": [
      {
        "type": "SWIPEABLE_MEDIA",
        "media_keys": [
          "13_1089771253848666112",
          "13_1191948012077092867"
        ]
      },
      {
        "type": "DETAILS",
        "title": "X",
        "destination": {
          "type": "WEBSITE",
          "url": "https://www.x.com/",
          "tco_url": "https://t.co/dyTMHWKWZb"
        }
      }
    ],
    "id": "ars7m",
    "created_at": "2020-11-11T07:51:47Z",
    "card_uri": "card://1326432421105995776",
    "updated_at": "2020-11-11T07:51:47Z",
    "deleted": false,
    "card_type": "UNIFIED"
  }
}

他のカードと同様に、カルーセルカードのレスポンスには card_uri が含まれており、ツイートを作成する際に使用します。

ツイート

ツイートを作成するには、POST accounts/:account_id/tweet エンドポイントを使用し、先ほどのリクエストで取得した card_uri を指定します。 (可読性のため、レスポンスは一部省略しています。)

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet_previews?tweet_type=PUBLISHED&tweet_ids=1326434098324385792"

{
  "data": {
    "created_at": "Wed Nov 11 07:58:27 +0000 2020",
    "id": 1326434098324385792,
    "id_str": "1326434098324385792",
    "text": "Swipe",
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "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": 756201191646691300,
      "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": {
      "text": "Swipe",
      "as_user_id": 756201191646691300,
      "card_uri": "card://1326432421105995776",
      "account_id": "18ce54d4x5t"
    }
  }
}

ツイートプレビュー

GET accounts/:account_id/tweet_previews エンドポイントを使用して、ツイートを確認してください。

​

クリエイティブ メタデータのタグ付け

​

はじめに

このガイドは、クリエイティブパートナー、代理店、およびクリエイティブ開発者を対象としており、Xキャンペーン内で使用されるアセットにタグ付けすることで、個々のアセットの価値とパフォーマンスをより正確に把握できるようにするものです。

注意: メディアアセットには、そのメディアアセットを作成したパートナーまたは開発者のみがタグを付与する必要があります。メディアアセットの利用者がそのメディアアセットを作成していない場合は、メタデータタグ付けを実装しないでください。

Creative Metadata Tagging は、クリエイティブパートナーによって作成された画像や動画について、アセットが X にアップロードされる場所やアップロードする主体を問わず、帰属情報を付与できるようにします。クリエイティブアセットとクリエイティブパートナーの関連付けを行うために、XMP 標準が使用されます。

​

クリエイティブアセットへのタグ付け

次の表は、各画像関連リソースのレスポンスで現在利用可能な識別子タイプと、それに対応する属性名を示しています。クリエイティブアセットにタグを付けるには、タグ付けツールが必要です。ExifTool (プラットフォームに依存しない Perl ライブラリと、メタ情報の読み取り・書き込み・編集用のコマンドラインアプリケーションのセット) を推奨します。サポートされているすべてのファイルタイプを参照してください。

ExifTool をインストールする手順に従ってください。Homebrew が提供しているソフトウェアパッケージを利用すると、macOS と Linux 向けの exiftool インストールコマンドが用意されており、インストールをさらに簡略化できます。コマンドラインで exiftool -ver を実行し、ツールのバージョン番号が返されることを確認して、正しくインストールされているか確かめてください。ExifTool のコマンドパラメータの詳細は ExifTool documentation を参照してください。

クリエイティブパートナーは、新規または既存のクリエイティブアセットに対して、自身の X app_id を contributor XMP タグおよび date タグにメタデータとして付与できます。クリエイティブアセットは、メディアのアップロード時と同じサイズ制限に従います。 

Note: X における contributor XMP タグの利用により、メタデータには X 上のキャンペーン専用の値のみが記録されるようになります。

exiftool -contributor="<YOUR APP ID>" -creative_file.jpg

exiftool -date="<date>" -creative_file.jpg

app_id は、開発者コンソール の「Projects & Apps」から確認できます。例: 16489123

次の例では、画像に対して、app_id を contributor タグとして、date を date タグとして追加しています。

app_id:858382169

date:2022-03-13

creative_file: eiffel_tower.jpg

exiftool -contributor=858382169 eiffel_tower.jpg

   1 image files updated

exiftool -date=2022-03-13 eiffel_tower.jpg

  1 image files updated

画像にタグ付けが正しく行われていることを確認してください： 

exiftool -xmp:all -G1 <filename>

例:

exiftool -xmp:all -G1 eiffel_tower.jpg

[XMP]        XMP Toolkit            : Image::ExifTool 12.30

[XMP]        Contributor            : 858382169

[XMP]        Date                   : 2022:03:13

​

質問はありますか？

タグ付けおよびアトリビューションが正しく行われているか確認したい場合は、タグ付け済みのアセットのサンプルを [e-mail] 宛てに送付し、X の担当者による確認を依頼してください。

​

APIリファレンス

​

アカウントメディア

​

GET accounts/:account_id/account_media

現在のアカウントに関連付けられているアカウントメディアの一部またはすべての詳細を取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/account_media

​

パラメーター

Name	Description
account_id required	対象アカウントの識別子です。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
account_media_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを目的のアカウントメディアのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 3wpx
count optional	各リクエストごとに取得するレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
creative_types optional	指定したクリエイティブタイプに一致するアカウントメディアのみにレスポンスを絞り込みます。複数のクリエイティブタイプを指定する場合は、enum 値をカンマ区切りで指定します。 Type: enum Possible values: BANNER, BANNER_TABLET, INTERSTITIAL, INTERSTITIAL_LANDSCAPE, INTERSTITIAL_LANDSCAPE_TABLET, INTERSTITIAL_TABLET, MEDIUM_RECTANGLE, PREROLL, VAST_PREROLL
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
sort_by optional	サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	リクエストに削除済みの結果を含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 注: このパラメーターと cursor は同時には使用できません。 注: total_count を含むリクエストには、より低いレート制限が適用されます (現在は 15 分あたり 200 回に設定されています) 。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media?account_media_ids=3wpx

​

レスポンス例

{
  "request": {
    "params": {
      "account_media_ids": [
        "3wpx"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_id": "13_771791717175468032",
      "media_url": null,
      "creative_type": "PREROLL",
      "id": "3wpx",
      "created_at": "2016-09-02T19:27:52Z",
      "updated_at": "2016-09-02T19:27:52Z",
      "deleted": false
    }
  ]
}

現在のアカウントに紐づく特定のアカウントメディアオブジェクトを取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id

​

パラメーター

Name	Description
account_id required	レバレッジド・アカウントを識別するための識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
account_media_id required	リクエストで操作対象となるアカウントメディアへの参照です。 Type: string Example: 2pnfd
with_deleted optional	削除済みの結果をリクエストに含めます。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd

​

レスポンス例

{
  "request": {
    "params": {
      "account_media_id": "2pnfd",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-07-28T01:44:41Z",
    "deleted": false
  }
}

現在のアカウントに紐づく指定されたアカウントメディアオブジェクトを削除します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id

​

パラメーター

Name	Description
account_id required	対象となるレバレッジドアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須となるパラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
account_media_id required	リクエストで操作する account media を指定します。 Type: string Example: 2pnfd

​

リクエスト例

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd

​

レスポンス例

{
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-08-25T17:16:26Z",
    "deleted": true
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "account_media_id": "2pnfd"
    }
  }
}

​

カード

注記: カードをツイートに関連付けるには、card_uri パラメータを POST accounts/:account_id/tweet、POST statuses/update、POST accounts/:account_id/scheduled_tweets、または POST accounts/:account_id/draft_tweets エンドポイントのいずれかで指定します。

現在のアカウントに関連付けられているカードの一部またはすべての詳細を取得します。

注記: これは、POST accounts/:account_id/cards エンドポイントを使用して作成されたカードのみを返します。その他のエンドポイントを使用して作成されたカードは返されません。

​

リソースURL

https://ads-api.x.com/12/accounts/:account_id/cards

​

パラメーター

Name	Description
account_id required	対象となるアカウントを識別するための識別子です。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_types optional	カンマ区切りの列挙値リストを指定して、レスポンスを必要なカードタイプのみに絞り込みます。 Type: enum Possible values: IMAGE_APP, IMAGE_CAROUSEL_APP, IMAGE_CAROUSEL_WEBSITE, IMAGE_MULTI_DEST_CAROUSEL_WEBSITE, IMAGE_WEBSITE, MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE, VIDEO_APP, VIDEO_CAROUSEL_APP, VIDEO_CAROUSEL_WEBSITE, VIDEO_MULTI_DEST_CAROUSEL_WEBSITE, VIDEO_WEBSITE
card_id optional	カンマ区切りの識別子リストを指定して、レスポンスを必要なカードのみに絞り込みます。最大 200 個のカード ID を指定できます。 Type: string Example: 1044294149527166979,1044301099031658496
card_uris optional	カンマ区切りの識別子リストを指定して、レスポンスを必要なカードのみに絞り込みます。最大 200 個のカード URI 値を指定できます。 Type: string Example: card://1044294149527166979,card://1044301099031658496
count optional	1 回のリクエストで取得を試みるレコード数を指定します。 Type: int Default: 100 Min, Max: 1, 200
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
include_legacy_cards optional	レスポンスに従来の Website カードおよび App カードを含めます。従来のカードとは、リソース URL が次の形式になっているカードを指します: accounts/:account_id/cards/:card_type。追加のコンテキストについては この開発者フォーラムの投稿 を参照してください。 Type: boolean Default: false Possible values: true, false
q optional	name によってカードを絞り込むための任意のクエリです。すべてを取得する場合はこのパラメーターを省略します。最大長: 80 文字。 Note: 大文字小文字を区別しない前方一致でマッチングを行います。 Type: string Example: dtc
sort_by optional	サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1

​

レスポンス例

{
  "request": {
    "params": {
      "count": 1,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": "8wzvldqtc",
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

現在のアカウントに関連付けられている1つのカードの詳細を取得します。

​

リソースURL

https://ads-api.x.com/12/accounts/:account_id/cards/:card_id

​

パラメーター

Name	Description
account_id required	レバレッジド・アカウントの識別子です。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_id required	カードの ID です。 Type: string Example: 1044294149527166979
with_deleted optional	リクエストに削除済みの結果を含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

​

レスポンス例

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

​

POST accounts/:account_id/cards

指定したアカウントに紐づく新しいカードを作成します。

Card 作成リクエストでは JSON 形式の POST ボディのみを受け付けます。Content-Type は application/json に設定する必要があります。

詳細な使用例については、Carousels ガイドを参照してください。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards

​

パラメーター

JSON の POST ボディには、カードの name と components の配列を含める必要があります。コンポーネントはオブジェクトとして表され、カードの広告主向け属性を記述します。

次の例は、ペイロードのおおまかな構造を示したものであり、動作しない情報が含まれています。

{
  "name": "some name",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}

以下にコンポーネントに関する追加情報を示します。

Name	Description
account_id required	対象アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
name required	カードの名前です。最大長: 80 文字。 Type: string Example: component based card
components sometimes required	カードを作成するために使用するコンポーネントを指定します。詳細は以下を参照してください。slides と同時には指定できません。注: コンポーネントの順序は重要です。 Type: array of objects
slides sometimes required	この配列の配列を使用して Multi-Destination Carousel を作成します。各カードをコンポーネントのグループとして表現します。各スライドはカードの完全な表現になっている必要があります。components と同時には指定できません。注: 各スライドの順序は重要です。 Type: array of array

​

コンポーネント

すべてのコンポーネントには、そのオブジェクトのスキーマを決定する type フィールドを含める必要があります。Ads API では、コンポーネントの種類として、メディアベースのコンポーネントと説明ベースのコンポーネントがサポートされています。

• メディア:
• MEDIA: 単一の動画または画像
• SWIPEABLE_MEDIA: 2〜6 個の動画または画像
• 説明:
• DETAILS
• BUTTON

各コンポーネントには必須フィールドのセットが定義されています (type キーに加えて) 。これらは次の表に示します。

Component type	Field	Value type
MEDIA	media_key	string
SWIPEABLE_MEDIA	media_keys	array of strings
DETAILS	title destination	string object
BUTTON	label destination	object object

次に示すのは、components 配列内における BUTTON コンポーネントの例です (意図的に name キーを省略しています) 。 (省略記号は、追加情報を指定する必要がある箇所を示しています。)

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        ...
      },
      "destination": {
        ...
      }
    }
  ]
}

コンポーネントオブジェクトが指定される順序によって、上から下へのレンダリング順序が定義されます。Card は、1 つのメディアベースのコンポーネントと、DETAILS または BUTTON コンポーネントのいずれかを使用して作成する必要があります。説明ベースのコンポーネントはメディアの下にレンダリングされ、URL またはモバイルアプリのいずれかを遷移先として関連付けます。

Label

Label はボタンに表示されるテキストを定義するため、BUTTON コンポーネントにのみ適用されます。Label オブジェクトには必須キーが 2 つあり、type と value の 2 つです。type は ENUM に設定する必要があり、value には BOOK、CONNECT、INSTALL、OPEN、ORDER、PLAY、SHOP のいずれかを指定できます。

前の例に基づき、以下は BUTTON コンポーネント内の label オブジェクトを示しています。

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        ...
      }
    }
  ]
}

リンク先

リンク先は、広告主がユーザーを誘導しようとする場所です。リンク先は常に DETAILS または BUTTON コンポーネント内で必須となります。リンク先の種類は WEBSITE と APP の2種類があります。

注記: Website リンク先は DETAILS コンポーネントでのみ使用でき、App リンク先は BUTTON コンポーネントでのみ使用できます。

Website リンク先

Name	Description
type required	リンク先の type。利用されるスキーマを決定します。 Type: enum Possible values: WEBSITE
url required	ユーザーをリダイレクトするウェブサイトの URL。 Type: string Example: https://devcommunity.x.com/c/advertiser-api

App リンク先

Name	Description
type required	リンク先の type。利用されるスキーマを決定します。 Type: enum Possible values: APP
country_code required	App が販売されている国を表す ISO 3166-1 alpha-2 の2文字コード。 Type: string Example: US
googleplay_app_id sometimes required	Google Play アプリケーションのパッケージ名。 注記: 次のいずれか一方は必須です: ios_app_store_identifier または googleplay_app_id。 Type: string Example: com.twitter.android
ios_app_store_identifier sometimes required	iOS App Store の識別子。 注記: 次のいずれか一方は必須です: ios_app_store_identifier または googleplay_app_id。 Type: string Example: 333903271
googleplay_deep_link optional	プロモーション対象の Android App へのディープリンク。 注記: googleplay_app_id が指定されている場合にのみ使用できます。 Type: string
ios_deep_link optional	プロモーション対象の iOS App へのディープリンク。 注記: ios_app_store_identifier が指定されている場合にのみ使用できます。 Type: string

​

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards

{
  "name": "components create cards",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1323490622599176192"
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android"
      }
    }
  ]
}

​

レスポンス例

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "components create cards",
    "components": [
      {
        "type": "MEDIA",
        "media_key": "3_1323490622599176192"
      },
      {
        "type": "BUTTON",
        "label": {
          "type": "ENUM",
          "value": "INSTALL"
        },
        "destination": {
          "type": "APP",
          "country_code": "US",
          "googleplay_app_id": "com.twitter.android"
        }
      }
    ],
    "created_at": "2020-11-11T05:42:25Z",
    "card_uri": "card://1326399865065238531",
    "id": "1321554298900107264",
    "updated_at": "2020-11-11T05:42:25Z",
    "deleted": false,
    "card_type": "IMAGE_APP"
  }
}

現在のアカウントに関連付けられている指定されたカードを更新します。

カードの編集リクエストでは JSON の POST ボディのみが受け付けられます。Content-Type は application/json に設定する必要があります。

​

リソースURL

https://ads-api.x.com/12/accounts/:account_id/cards/1321554298900107264

​

パラメーター

POST リクエストの JSON ボディには、更新されるパラメーターを含める必要があります。リクエストは、ペイロード内で指定されたパラメーターで各フィールドを置き換えます。コンポーネントはオブジェクトとして表現され、カードの広告主向け属性を記述します。

次の例は、ペイロードの一般的な構造を示したものであり (実際には動作しない値が含まれています) 。

{
  "name": "some name",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}

POST accounts/:account_id/cards における components と slides の追加情報。

Name	Description
account_id required	対象の広告アカウントを示す識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
name optional	カードの名前です。最大長: 80 文字。 型: string 例: component based card
components optional	カードを更新するために使用する components を指定します。追加情報は下記を参照してください。slides と同時には指定できません。注意: components の順序は重要です。 型: array of objects
slides optional	Multi-Destination Carousels (マルチデスティネーションカルーセル) を更新するために、この二次元配列を使用します。各カードを components のグループとして記述します。各スライドは 1 枚のカードを完全に表現している必要があります。components と同時には指定できません。注意: 各スライドの順序は重要です。 型: array of array

​

リクエスト例

この例では、前述の例の components フィールドに対して、name を更新し、media_keys の 1 つを削除します。

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

{
  "name": "changed name",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "3_1075096386931052545"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "OPEN"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android",
        "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
      }
    }
  ]
}

​

レスポンス例

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "changed name",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

現在のアカウントに紐づく指定されたカードを削除します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/:card_id

​

Parameters

Name	Description
account_id 必須	レバレッジアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_id 必須	削除対象のカードの id。 Type: string Example: 1044294149527166979

​

リクエスト例

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

​

レスポンス例

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": true,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

​

カードの取得

現在のアカウントに関連付けられている、card_uri で識別される複数のカードを取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/all

​

パラメーター

Name	Description
account_id required	レバレッジアカウントを識別するための識別子です。リソースのパス内に含まれ、GET accounts を除くほとんどの Advertiser API リクエストで必須となるパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_uris required	カンマ区切りの識別子リストを指定して、レスポンスを対象のカードのみに限定します。最大 200 個までの card URI 値を指定できます。 Type: string Example: card://1044294149527166979,card://1044301099031658496
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all?card_uris=card://1044294149527166979,card://1044301099031658496

​

レスポンス例

{
  "request": {
    "params": {
      "card_uris": [
        "card://1044294149527166979",
        "card://1044301099031658496"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "name": "X App",
      "googleplay_app_id": "com.twitter.android",
      "image_display_height": "836",
      "country_code": "US",
      "id": "692xn",
      "wide_app_image": "https://pbs.twimg.com/media/Dc263l9VwAAAeEH.jpg",
      "created_at": "2018-09-24T18:35:01Z",
      "image_display_width": "1600",
      "card_uri": "card://1044294149527166979",
      "updated_at": "2018-09-24T18:35:01Z",
      "app_cta": "INSTALL",
      "deleted": false,
      "card_type": "IMAGE_APP_DOWNLOAD"
    },
    {
      "video_poster_height": "9",
      "name": "Developer Platform",
      "website_shortened_url": "https://t.co/zadeUSVD18",
      "video_height": "9",
      "video_url": "https://video.twimg.com/amplify_video/vmap/991374284135137280.vmap",
      "content_duration_seconds": "24",
      "video_owner_id": "756201191646691328",
      "video_content_id": "13_991374284135137280",
      "website_display_url": "developer.x.com",
      "id": "6933h",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/991374284135137280/pl/sQrBsE9mFvNep9Cx.m3u8?tag=2",
      "website_dest_url": "https://developer.x.com",
      "created_at": "2018-09-24T19:02:38Z",
      "card_uri": "card://1044301099031658496",
      "title": "Developer Platform",
      "website_url": "https://developer.x.com",
      "updated_at": "2018-09-24T19:02:38Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/991374284135137280/img/YbbGQHvWRjoFgrLz.jpg",
      "video_poster_width": "16",
      "deleted": false,
      "card_type": "VIDEO_WEBSITE"
    }
  ]
}

card_id を指定して、現在のアカウントに関連付けられている特定のカードを取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/all/:card_id

​

パラメータ

Name	Description
account_id required	レバレッジドアカウントの識別子です。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
card_id required	リクエストで操作対象となる Card への参照です。 型: string 例: 508pf
with_deleted optional	削除済みの結果をレスポンスに含めます。 型: boolean デフォルト: false 指定可能な値: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all/508pf

​

レスポンス例

{
  "request": {
    "params": {
      "card_id": "508pf",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_poster_height": "9",
    "name": "ビデオウェブサイトカード",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/867520357225418752.vmap",
    "content_duration_seconds": "21",
    "video_owner_id": "756201191646691328",
    "video_content_id": "13_867520357225418752",
    "website_display_url": "developer.x.com",
    "id": "508pf",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/867520357225418752/pl/TPHeH5ZlHFCa2TeJ.m3u8",
    "website_dest_url": "https://developer.x.com/en/docs/ads/creatives/api-reference/video-website#post-accounts-account-id-cards-video-website",
    "created_at": "2017-11-10T09:00:35Z",
    "card_uri": "card://928910245920829440",
    "title": "VWC",
    "website_url": "https://t.co/F81hp59pUF",
    "updated_at": "2018-01-05T05:43:31Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/867520357225418752/img/E3pnXM0sCKnRsFih.jpg",
    "video_poster_width": "16",
    "deleted": false,
    "card_type": "VIDEO_WEBSITE"
  }
}

​

下書きツイート

​

GET accounts/:account_id/draft_tweets

現在のアカウントに紐づく一部またはすべての下書きツイートの詳細情報を取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/draft_tweets

​

パラメーター

Name	Description
account_id required	レバレッジド アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
count optional	1 回のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 100 Min, Max: 1, 200
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: c-jh1g0ryb
user_id optional	ツイートの下書きを取得するユーザーを指定します。設定しない場合、当該アカウントの FULL プロモータブルユーザーがデフォルトになります。 Type: string Example: 756201191646691328

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?count=1

​

レスポンス例

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name" null,
      "text": "hello, world",
      "user_id": "756201191646691328",
      "id": "994791681219231744",
      "nullcast": true,
      "created_at": "2018-05-11T04:09:53Z",
      "card_uri": null,
      "updated_at": "2018-05-11T04:09:53Z",
      "media_keys": []
    }
  ],
  "next_cursor": "c-jh1g0ryb"
}

現在のアカウントに紐づく特定の下書きツイートを取得します。

​

リソースURL

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id

​

パラメーター

Name	Description
account_id required	レバレッジドアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
draft_tweet_id required	リクエストで操作対象となる Draft Tweet への参照です。 Type: string Example: 994788364334325760

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994788364334325760

​

レスポンス例

{
  "request": {
    "params": {
      "draft_tweet_id": "994788364334325760"
    }
  },
  "data": {
    "name": null,
    "text": "#TwitterDev",
    "user_id": "756201191646691328",
    "id": "994788364334325760",
    "nullcast": true,
    "created_at": "2018-05-11T03:56:42Z",
    "card_uri": "card://958225772740714496",
    "updated_at": "2018-05-11T03:56:42Z",
    "media_keys": []
  }
}

​

POST accounts/:account_id/draft_tweets

アカウントのフルプロモーション可能ユーザー (デフォルト) 、または as_user_id パラメータで指定したユーザー用の下書きツイートを作成します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/draft_tweets

​

Parameters

名前	説明
account_id 必須	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
as_user_id 必須	ツイートを代理投稿する広告主のユーザー ID です。広告主は、ads.x.com を通じて、自分の広告アカウントへのアクセス権をあなたのハンドル (または複数のハンドル) に付与する必要があります。この権限により、広告主のトークンではなく、自分のハンドルの OAuth トークンを使用して API を呼び出せるようになります。 型: string 例: 756201191646691328
text 条件付き必須	ステータス更新のテキストです。media_keys が指定されていない場合は必須です。 型: string 例: Just setting up my X.
card_uri 任意	利用可能な場合は、任意のカードのレスポンスの card_uri 値を使用して、そのツイートにカードを関連付けます。 型: string 例: card://960880280705392541
media_keys 任意	カンマ区切りの識別子リストを指定して、ツイートにメディアを関連付けます。画像は最大 4 枚、アニメーション GIF は 1 件、動画は 1 件まで含めることができます。 注: メディアアセットは、そのアカウントの Media Library に存在している必要があります。 型: string 例: 13_1153584529292270722
nullcast 任意	nullcast (「プロモーション専用」) されたツイートを作成するかどうか。 型: boolean デフォルト: true 取りうる値: true, false
name 任意	下書きツイートの名前です。最大文字数: 80 文字。 型: string 例: Tweet with name

​

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.

​

レスポンス例

{
  "request": {
    "params": {
      "text": "Just setting up my X.",
      "as_user_id": "756201191646691328"
    }
  },
  "data": {
    "name": null,
    "text": "Just setting up my X.",
    "user_id": "756201191646691328",
    "id": "994747471329873920",
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:14:13Z",
    "media_keys": []
  }
}

現在のアカウントの指定された下書きツイートを更新します。

​

リソースのURL

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id

​

パラメーター

Name	Description
account_id 必須	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメーターです。指定されたアカウントは認証済みユーザーに紐づいている必要があります。 Type: string Example: 18ce54d4x5t
draft_tweet_id 必須	リクエスト内で操作対象となる Draft Tweet (下書きツイート) への参照です。 Type: string Example: 994747471329873920
card_uri 任意	利用可能な場合、任意の cards レスポンスから取得した card_uri 値を使用してツイートにカードを関連付けます。 Note: 値を指定せずにパラメーターのみを指定すると、未設定 (削除) されます。 Type: string Example: card://970582057284129151
media_keys 任意	カンマ区切りの識別子のリストを指定して、ツイートにメディアを関連付けます。画像は最大 4 枚、アニメーション GIF は 1 つ、または動画は 1 つまで含めることができます。 Note: メディアアセットはアカウントの Media Library 内に存在している必要があります。 Note: 値を指定せずにパラメーターのみを指定すると、未設定 (削除) されます。 Type: string Example: 13_1153584529292270722
nullcast 任意	nullcast (「Promoted-only」) されたツイートを作成するかどうか。 Type: boolean Possible values: true, false
text 任意	ステータス更新のテキストです。 Type: string Example: just setting up my twttr
name 任意	Draft Tweet の名前です。最大 80 文字。 Type: string Example: Tweet with name

​

リクエスト例

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994747471329873920?text=just setting up my twttr

​

レスポンス例

{
  "request": {
    "params": {
      "draft_tweet_id": 994747471329873920,
      "text": "just setting up my twttr"
    }
  },
  "data": {
    "name": null,
    "text": "just setting up my twttr",
    "user_id": "756201191646691328",
    "id": "994747471329873920",
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:16:59Z",
    "media_keys": []
  }
}

現在のアカウントに属する指定された下書きツイートを完全に削除します。

注意: ツイートまたは予約ツイートをそのメタデータを使用して作成したら、下書きは削除することを強く推奨します。

注意: これは完全削除です。この操作を行うと、削除された下書きツイートを復元することはできません。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id

​

パラメーター

名前	説明
account_id required	レバレッジドアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須となるパラメーターです。指定されたアカウントは認証済みユーザーに紐づいている必要があります。 型: string 例: 18ce54d4x5t
draft_tweet_id required	リクエストで操作する下書きツイート (Draft Tweet) を参照する id です。 型: string 例: 994787835663155200

​

リクエスト例

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200

​

レスポンス例

{
  "request": {
    "params": {
      "draft_tweet_id": "994787835663155200"
    }
  },
  "data": {
    "name": null,
    "text": "hello, world",
    "user_id": "756201191646691328",
    "id": "994787835663155200",
    "nullcast": true,
    "status": "DELETED",
    "created_at": "2018-05-11T03:54:36Z",
    "card_uri": null,
    "updated_at": "2018-05-11T04:07:31Z",
    "media_keys": []
  }
}

​

POST accounts/:account_id/draft_tweets/preview/:draft_tweet_id

モバイルデバイス上で下書きツイートをプレビューします。

リクエストが成功すると、認証済みユーザーがログインしているすべてのデバイスに通知が送信されます。通知をタップするとタイムラインが開き、ユーザーは下書きツイートを表示して操作できるようになり、自動再生、音量、全画面表示、動画ウェブサイトカードのドッキングなどの動作をテストできます。

注: 端末上でのプレビューは、通知を受け取ったユーザーにしか表示されません。

注: 通知は X の公式アプリにのみ送信されます。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_id

​

パラメーター

Name	Description
account_id required	レバレッジド・アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定されたアカウントは、認証済みユーザーに紐づいている必要があります。 型: string 例: 18ce54d4x5t
draft_tweet_id required	このリクエストで操作対象となる Draft ツイートを指す参照。 型: string 例: 996132315829948416

​

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416

​

レスポンス例

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "draft_tweet_id": "996132315829948416"
    }
  },
  "message": "See @apimctestface's notifications in the X app to preview your Tweet."
}

​

画像会話カード

注意: カードをツイートに関連付けるには、card_uri パラメータを POST accounts/:account_id/tweet、POST statuses/update、または POST accounts/:account_id/scheduled_tweets エンドポイントのいずれかで指定してください。

​

GET accounts/:account_id/cards/image_conversation

現在のアカウントに関連付けられているイメージ会話カードの一部またはすべての情報を取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation

​

Parameters

Name	Description
account_id required	レバレッジド・アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_ids optional	カンマ区切りの識別子のリストを指定することで、レスポンスを目的の image conversation card のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 59woh
count optional	各リクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	結果の次のページを取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
q optional	name で card を絞り込むための任意のクエリです。すべてを取得する場合はこのパラメータを省略します。最大長：80 文字。 Note: 大文字・小文字を区別しない前方一致で検索します。 Type: string Example: night
sort_by optional	サポートされている属性で、昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメータと cursor は同時には指定できません。 Note: total_count を含むリクエストのレート制限はより厳しく、現在は 15 分あたり 200 件に設定されています。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?card_ids=59woh

​

サンプルレスポンス

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_ids": [
        "59woh"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "image conversation card",
      "first_cta": "#moon",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "thanks",
      "id": "59woh",
      "first_cta_tweet": "stars",
      "media_key": "3_957113581522141184",
      "created_at": "2018-01-27T04:58:42Z",
      "image_display_width": "1280",
      "card_uri": "card://923498485702009837",
      "title": "Full moon",
      "updated_at": "2018-01-27T04:58:42Z",
      "deleted": false,
      "card_type": "IMAGE_CONVERSATION"
    }
  ]
}

現在のアカウントに関連付けられた特定の画像会話カードを取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

パラメーター

Name	Description
account_id 必須	対象となるアカウントを識別する ID です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメーターです。指定したアカウントは認証済みユーザーに紐づいている必要があります。 Type: string Example: 18ce54d4x5t
card_id 必須	リクエストで操作対象となる Image Conversation Card を参照する ID です。 Type: string Example: 59woh
with_deleted 任意	削除済みの結果をレスポンスに含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh

​

レスポンス例

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_id": "59woh",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "image conversation card",
    "first_cta": "#moon",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "thanks",
    "id": "59woh",
    "first_cta_tweet": "stars",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "Full moon",
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  }
}

​

POST accounts/:account_id/cards/image_conversation

指定したアカウントに関連付けられた新しい image conversation カードを作成します。

画像を当社のエンドポイントにアップロードする際に役立つ情報については、Uploading Media を参照してください。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation

​

Parameters

Name	Description
account_id required	対象となるアカウントの識別子。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
first_cta required	最初のオプションの Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字 (# は文字数に含めません) 。 Type: string Example: #ShareNow
first_cta_tweet required	最初の CTA がクリックされたときに使用されるツイート本文。 Type: string Example: I Heart @AdsAPI
media_key required	このカードで使用する画像の media key。 Note: 画像はアカウントの Media Library 内に存在している必要があります。 Note: 画像の最小幅は 800px で、幅:高さのアスペクト比は 1.91:1 である必要があります。 Type: string Example: 3_1151345051104991073
name required	カードの名前。 Type: string Example: image conversation card
thank_you_text required	CTA がクリックされた後に表示されるテキスト。最大長: 23 文字。 Type: string Example: Thank you
second_cta sometimes required	2 番目のオプションの Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字 (# は文字数に含めません) 。 Type: string Note: title が設定されていない場合に必須です。 Example: #ShareAgain
second_cta_tweet sometimes required	2 番目の CTA がクリックされたときに使用されるツイート本文。 Note: second_cta が設定されている場合に必須です。 Type: string Example: I Heart @AdsAPI Again
title sometimes required	カードのタイトル。画像の下、CTA の上に表示されます。最大長: 23 文字。 Type: string Note: second_cta が設定されていない場合に必須です。 Example: Start a conversation
third_cta optional	3 番目のオプションの Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字 (# は文字数に含めません) 。 Type: string Example: #ShareMore
third_cta_tweet sometimes required	3 番目の CTA がクリックされたときに使用されるツイート本文。 Type: string Note: third_cta が設定されている場合に必須です。 Example: I Heart @TwitterDev
fourth_cta optional	4 番目のオプションの Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字 (# は文字数に含めません) 。 Type: string Example: #ShareExtra
fourth_cta_tweet sometimes required	4 番目の CTA がクリックされたときに使用されるツイート本文。 Type: string Note: fourth_cta が設定されている場合に必須です。 Example: I Heart @TwitterDev Again
unlocked_image_media_key optional	インスタントアンロックシナリオで使用される画像の media_key。これは書き込み専用フィールドです。レスポンスでは、この画像用の X URL が API によって返されます。 Note: 画像はアカウントのメディアライブラリ内に存在している必要があります。 Note: 画像の最小幅は 800px で、幅:高さのアスペクト比は 5:2 である必要があります。 Type: string Example: 3_883112887618682880
thank_you_url optional	サンクス用テキストとともに表示される URL。 Type: string Example: https://example.com/thankyou

​

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?media_key=3_957113581522141184&name=image conversation card&first_cta=#moon&first_cta_tweet=stars&thank_you_text=thanks&title=Full moon

​

レスポンス例

{
  "data": {
    "name": "image conversation card",
    "first_cta": "#moon",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "thanks",
    "id": "59woh",
    "first_cta_tweet": "stars",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "Full moon",
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "name": "image conversation card",
      "first_cta": "#moon",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "thanks",
      "media_key": "3_957113581522141184",
      "account_id": "18ce54d4x5t",
      "first_cta_tweet": "stars",
      "image_display_width": "1280",
      "title": "Full moon",
      "card_type": "IMAGE_CONVERSATION"
    }
  }
}

現在のアカウントに紐づく指定した画像会話カードを更新します。

エンドポイントへの画像アップロードの詳細については、Uploading Media を参照してください。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

Parameters

Name	Description
account_id required	レバレッジドアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_id required	リクエストで操作対象となる Image Conversation Card への参照です。 Type: string Example: 4i0qg
first_cta optional	1 番目のオプション用の Call-To-Action (CTA) ハッシュタグです。最大長: 20 文字 (# はカウントしません) 。 Type: string Example: #ShareNow
first_cta_tweet optional	最初の CTA がクリックされたときに使用されるツイート本文です。 Type: string Example: I Heart @AdsAPI
second_cta optional	2 番目のオプション用の Call-To-Action (CTA) ハッシュタグです。最大長: 20 文字 (# はカウントしません) 。 Type: string Note: title が設定されていない場合は必須です。 Example: #ShareAgain
second_cta_tweet optional	2 番目の CTA がクリックされたときに使用されるツイート本文です。 Note: second_cta が設定されている場合は必須です。 Type: string Example: I Heart @AdsAPI Again
third_cta optional	3 番目のオプション用の Call-To-Action (CTA) ハッシュタグです。最大長: 20 文字 (# はカウントしません) 。 Type: string Example: #ShareMore
third_cta_tweet optional	3 番目の CTA がクリックされたときに使用されるツイート本文です。 Type: string Note: third_cta が設定されている場合は必須です。 Example: I Heart @TwitterDev
fourth_cta optional	4 番目のオプション用の Call-To-Action (CTA) ハッシュタグです。最大長: 20 文字 (# はカウントしません) 。 Type: string Example: #ShareExtra
fourth_cta_tweet optional	4 番目の CTA がクリックされたときに使用されるツイート本文です。 Type: string Note: fourth_cta が設定されている場合は必須です。 Example: I Heart @TwitterDev Again
media_key optional	このカードで使用される画像の media key です。 Note: 画像はアカウントの Media Library に存在している必要があります。 Note: 最小画像幅は 800px で、幅:高さのアスペクト比が 1.91:1 である必要があります。 Type: string Example: 3_1151345051104991073
name optional	カードの名前です。 Type: string Example: moon card
thank_you_text optional	CTA がクリックされた後に表示されるテキストです。最大長: 23 文字。 Type: string Example: Thank you
thank_you_url optional	お礼テキストと一緒に表示される URL です。 Type: string Example: https://example.com/thankyou
title optional	カードのタイトルです。画像の下、CTA の上に表示されます。最大長: 23 文字。 Type: string Note: second_cta が設定されていない場合は必須です。 Example: Start a conversation
unlocked_image_media_key optional	インスタントアンロックのシナリオで使用される画像の media_key です。これは書き込み専用フィールドです。レスポンスでは、この画像用の X 上での URL が API から返されます。 Note: 画像はアカウントのメディアライブラリ内に存在している必要があります。 Note: 最小画像幅は 800px で、幅:高さのアスペクト比が 5:2 である必要があります。 Type: string Example: 3_883112887618682880

​

リクエスト例

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card

​

レスポンス例

{
  "data": {
    "name": "moon card",
    "id": "59woh",
    "created_at": "2018-01-27T04:58:42Z",
    "card_uri": "card://923498485702009837",
    "updated_at": "2018-01-29T21:04:39Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "IMAGE_CONVERSATION",
      "card_id": "59woh",
      "name": "moon card"
    }
  }
}

現在のアカウントに紐づく指定の画像会話カードを完全に削除します。

注記: これは完全削除です。削除したカードを復元することはできません。

​

リソースURL

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

Parameters

Name	Description
account_id required	操作対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
card_id required	このリクエストで操作する Image Conversation Card を指定するための参照。 型: string 例: 4i0qe

​

リクエスト例

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/4i0qe

​

レスポンス例

{
  "data": {
    "name": "image conversation card",
    "id": "4i0qe",
    "created_at": "2017-07-07T00:03:01Z",
    "updated_at": "2017-08-23T13:26:23Z",
    "deleted": true,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0qe",
      "card_type": "image_conversation",
      "account_id": "18ce54d4x5t"
    }
  }
}

​

メディアライブラリ

​

GET accounts/:account_id/media_library

現在のアカウントに関連付けられているメディアライブラリオブジェクトの一部またはすべての詳細を取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/media_library

​

パラメータ

Name	Description
account_id required	レバレッジドアカウント (leveraged account) の識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般に必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
count optional	1 回のリクエストで取得を試みるレコード数を指定します。 Type: int Default: 20 Min, Max: 1, 50
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: c-1
media_type optional	レスポンスを、目的のメディア種別のみに絞り込みます。 Type: enum Possible values: GIF, IMAGE, VIDEO
q optional	name、title、file_name、description フィールドでリソースを絞り込むための任意指定のクエリです。 Note: 大文字小文字を区別しない term マッチングを行います。 Type: string Min, Max length: 1, 255

​

リクエスト例

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

​

レスポンスの例

{
  "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"
}

現在のアカウントに関連付けられている指定のメディアライブラリオブジェクトを取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

パラメーター

Name	Description
account_id required	レバレッジド・アカウントを識別するための識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須となるパラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
media_key required	リクエストで操作対象となるメディアライブラリ内のオブジェクトを参照するキーです。 Type: string Example: 13_909110614026444802

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/13_909110614026444802

​

レスポンス例

{
  "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
  }
}

メディアオブジェクトをこのアカウントに関連付けます。詳細については、Media Library ガイドをご覧ください。

注: AMPLIFY_VIDEO メディアカテゴリの動画を Media Library に追加すると、その動画は自動的に PREROLL の account_media アセットとして利用可能になります。

​

リソースURL

https://ads-api.x.com/12/accounts/:account_id/media_library

​

パラメーター

Name	Description
account_id required	対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須となるパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
media_key required	アップロードされたコンテンツの media_key。media_category が指定されている場合、POST media/upload のレスポンスで media_key が返されます。 型: string 例: 3_931236738554519552
description optional	ツイートされたときに動画の下に表示される説明文。最大文字数: 200 文字。 これはデフォルトではツイート内に表示されません。動画の description を表示するには、POST accounts/:account_id/tweet エンドポイントで video_description パラメーターを使用します。 注: 動画にのみ使用できます。 型: string 例: This is the description under the video.
file_name optional	メディアライブラリオブジェクトのファイル名。最大長: 255。 ファイル名は ads.x.com の Media Library UI 内で、各メディアアセットのメディア詳細に表示されます。file_name が設定されていない場合は空になります。 型: string 例: coffee.jpeg
name optional	メディアライブラリオブジェクトの名前。最大長: 100。 これは ads.x.com の Media Library UI 内の各メディアアセットの下に表示されるラベルです。name が設定されていない場合、ラベルは「Untitled」になります。 型: string 例: Latte
poster_media_key optional	アップロード済み画像の media_key を使用して、動画のポスター画像を指定します。指定しない場合は最初のフレームが使用されます。 注: 動画にのみ使用できます。 型: string 例: 3_890599134483242005
title optional	ツイートされたときに動画の下に表示されるタイトル (見出し) 。最大文字数: 70 文字。 これはデフォルトではツイート内に表示されません。動画の title を表示するには、POST accounts/:account_id/tweet エンドポイントで video_title パラメーターを使用します。 注: 動画にのみ使用できます。 型: string 例: Video title

​

リクエスト例

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

​

レスポンス例

{
  "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
  }
}

現在のアカウントのメディアライブラリ内にある指定のオブジェクトを更新します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

パラメーター

Name	Description
account_id 必須	レバレッジド アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常、必須パラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
media_key 必須	リクエストで操作するメディアライブラリオブジェクトを指定します。 Type: string Example: 16_844800354743074820
description 任意	ツイートされた際に動画の下に表示される説明文です。最大文字数: 200 文字。 この説明文は既定ではツイート内に表示されません。動画の description を表示するには、POST accounts/:account_id/tweet エンドポイントで video_description パラメーターを使用してください。 注: 動画でのみ使用できます。 Type: string Example: This is the description under the video.
file_name 任意	メディアライブラリオブジェクトのファイル名です。最大長: 255。 ファイル名は、ads.x.com の Media Library UI 内のすべてのメディアアセットのメディア詳細で確認できます。file_name が設定されていない場合、この値は空になります。 Type: string Example: coffee.jpeg
name 任意	メディアライブラリオブジェクトの名称です。最大長: 100。 これは、ads.x.com の Media Library UI 内のすべてのメディアアセットの下に表示されるラベルです。name が設定されていない場合、ラベルは “Untitled” になります。 Type: string Example: Latte
poster_media_key 任意	アップロード済み画像の media_key を使用して、動画のポスター画像を指定します。 注: 動画でのみ使用できます。 Type: string Example: 3_885003359340375465
title 任意	ツイートされた際に動画の下に表示されるタイトル (見出し) です。最大文字数: 70 文字。 このタイトルは既定ではツイート内に表示されません。動画の title を表示するには、POST accounts/:account_id/tweet エンドポイントで video_title パラメーターを使用してください。 注: 動画でのみ使用できます。 Type: string Example: Video title

​

リクエスト例

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

​

レスポンスの例

{
  "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
  }
}

現在のアカウントに属する指定されたメディアライブラリオブジェクトを削除します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

Parameters

Name	Description
account_id 必須	利用対象となるアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
media_key 必須	リクエスト内で操作対象となるメディアライブラリオブジェクトを参照するキー。 Type: string Example: 7_860318603387600896

​

リクエスト例

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/7_860318603387600896

​

レスポンス例

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "7_860318603387600896"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 14330,
    "name": "mountains-on-ads.x.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.x.com",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-05-05T02:26:58Z",
    "deleted": true
  }
}

​

投票カード

​

GET accounts/:account_id/cards/poll

現在のアカウントに関連付けられている一部またはすべての poll カードの詳細を取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/poll

​

パラメーター

Name	Description
account_id required	レバレッジアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを目的の投票カードのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 57i77
count optional	各リクエストで取得を試行するレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
q optional	name でカードを絞り込むための任意のクエリです。すべて取得するにはこのパラメーターを省略します。最大長: 80 文字。 Note: 大文字・小文字を区別しない前方一致検索を行います。 Type: string Example: night
sort_by optional	サポートされている属性を、昇順または降順でソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	レスポンスに total_count 属性を含めます。 Note: このパラメーターと cursor は同時に指定できません。 Note: total_count を含むリクエストには、現在 15 分あたり 200 回に設定されている、より厳しいレート制限が適用されます。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?card_ids=57i77

​

レスポンス例

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_ids": [
        "57i77"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_poster_height": "9",
      "name": "ベストコースト投票",
      "start_time": "2018-01-09T04:51:34Z",
      "first_choice": "East",
      "video_height": "9",
      "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
      "content_duration_seconds": "8",
      "second_choice": "West",
      "end_time": "2018-01-16T04:51:34Z",
      "id": "57i77",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
      "created_at": "2018-01-09T04:51:34Z",
      "duration_in_minutes": "10080",
      "card_uri": "card://950590850777497601",
      "updated_at": "2018-01-09T04:51:34Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
      "video_poster_width": "16",
      "deleted": false,
      "card_type": "VIDEO_POLLS"
    }
  ]
}

現在のアカウントに紐付いている特定の投票カードを取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id

​

パラメーター

Name	Description
account_id required	レバレッジドアカウントを示す識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_id required	リクエスト内で操作対象となる poll card への参照です。 Type: string Example: 57i8t
with_deleted optional	削除済みの結果をリクエストに含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i8t

​

レスポンスの例

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_id": "57i8t",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "text only poll",
    "start_time": "2018-01-09T05:03:05Z",
    "first_choice": "Morning",
    "second_choice": "Evening",
    "end_time": "2018-01-11T05:03:05Z",
    "id": "57i8t",
    "created_at": "2018-01-09T05:03:05Z",
    "duration_in_minutes": "2880",
    "card_uri": "card://950593749658189824",
    "updated_at": "2018-01-09T05:03:05Z",
    "deleted": false,
    "card_type": "TEXT_POLLS"
  }
}

​

POST accounts/:account_id/cards/poll

指定したアカウントに関連付けられた新しい投票カードを作成します。このエンドポイントでは、画像付き、動画付き、またはメディアなしの投票カードを作成できます。メディア付きの投票は Media Forward Polls と呼ばれます。

注: Media Forward Polls 製品はベータ版であり、PROMOTED_MEDIA_POLLS アカウント機能が必要です。

注: 投票カードを更新 (PUT) することはできません。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/poll

​

パラメーター

Name	Description
account_id required	レバレッジド・アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須となるパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
duration_in_minutes required	投票が開かれた状態を維持する時間 (分) 。指定された duration_in_minutes が経過すると、投票は終了し、それ以上の投票は受け付けられません。これはレスポンス内の end_time に対応します。 Note: これはカードが作成された時点で開始され、ツイートに追加された時点ではありません。 Type: int Min, Max: 5, 10080
first_choice required	1 番目の投票選択肢。最大 25 文字。 Type: string Example: One
name required	カードの名前。 Type: string Example: poll card
second_choice required	2 番目の投票選択肢。最大 25 文字。 Type: string Example: Two
fourth_choice optional	4 番目の投票選択肢。最大 25 文字。 Note: このパラメーターを使用する場合は、1 番目、2 番目、3 番目の選択肢が設定されている必要があります。 Type: string Example: Four
media_key optional	このカードで使用する、メディアライブラリ内の画像または動画を示す media_key。これは書き込み専用フィールドです。レスポンスでは、このメディアに対する X の URL が返されます。 Note: 画像または動画はアカウントのメディアライブラリ内に存在している必要があります。 Note: 画像の最小幅は 800px で、幅:高さのアスペクト比は 1.91:1 である必要があります。
third_choice optional	3 番目の投票選択肢。最大 25 文字。 Note: このパラメーターを使用する場合は、1 番目と 2 番目の選択肢が設定されている必要があります。 Type: string Example: Three

​

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?duration_in_minutes=10080&first_choice=East&second_choice=West&media_key=13_950589518557540353&name=best coast poll

​

レスポンス例

{
  "request": {
    "params": {
      "first_choice": "East",
      "name": "best coast poll",
      "second_choice": "West",
      "media_key": "13_950589518557540353",
      "duration_in_minutes": 10080
    }
  },
  "data": {
    "video_poster_height": "9",
    "name": "best coast poll",
    "start_time": "2018-01-09T04:51:34Z",
    "first_choice": "East",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
    "content_duration_seconds": "8",
    "second_choice": "West",
    "end_time": "2018-01-16T04:51:34Z",
    "id": "57i77",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
    "created_at": "2018-01-09T04:51:34Z",
    "duration_in_minutes": "10080",
    "card_uri": "card://950590850777497601",
    "updated_at": "2018-01-09T04:51:34Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
    "video_poster_width": "16",
    "deleted": false,
    "card_type": "VIDEO_POLLS"
  }
}

現在のアカウントに属する指定の投票カードを永久に削除します。

注: これはハード削除です。この操作を行うと、削除されたカードを復元することはできません。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id

​

パラメーター

Name	Description
account_id 必須	レバレッジドアカウントの識別子です。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_id 必須	リクエスト内で操作対象となる poll カードを示します。 Type: string Example: 57i9t

​

リクエスト例

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t

​

レスポンスの例

{
  "data": {
    "name": "poll with image",
    "start_time": "2018-01-09T05:10:51Z",
    "id": "57i9t",
    "created_at": "2018-01-09T05:10:51Z",
    "updated_at": "2018-01-09T05:11:04Z",
    "deleted": true,
    "card_type": "IMAGE_POLLS"
  },
  "request": {
    "params": {
      "card_id": "57i9t",
      "card_type": "poll",
      "account_id": "18ce54d4x5t"
    }
  }
}

​

Preroll Call To Actions

​

GET accounts/:account_id/preroll_call_to_actions

現在のアカウント内のラインアイテムに関連付けられている、一部またはすべてのプレロール Call-To-Action (CTA) の詳細を取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions

​

Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_ids optional	カンマ区切りの識別子リストを指定して、レスポンスを指定した Line Item に関連付けられた preroll CTA のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 8v53k
count optional	1 回のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
preroll_call_to_action_ids optional	カンマ区切りの識別子リストを指定して、レスポンスを対象の preroll CTA のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 8f0
sort_by optional	サポートされている属性を昇順または降順でソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメータと cursor は同時には使用できません。 Note: total_count を含むリクエストには、現在 15 分あたり 200 に設定されている、より低いレート制限が適用されます。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_ids=8v53k

​

レスポンス例

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "line_item_ids": [
        "8v53k"
      ]
    }
  },
  "next_cursor": null,
  "data": [
    {
      "line_item_id": "8v53k",
      "call_to_action_url": "https://www.x.com",
      "call_to_action": "VISIT_SITE",
      "id": "8f0",
      "created_at": "2017-07-07T19:28:40Z",
      "updated_at": "2017-07-07T19:28:40Z",
      "deleted": false
    }
  ]
}

このアカウントに紐付いている特定のコールトゥアクション (CTA) を取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

パラメーター

Name	Description
account_id 必須	レバレッジドアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは、認証済みユーザーに紐づいている必要があります。 型: string 例: 18ce54d4x5t
preroll_call_to_action_id 必須	このリクエストで操作する preroll call to action への参照です。 型: string 例: 8f0
with_deleted 任意	削除済みの結果をリクエストに含めます。 型: boolean デフォルト: false 取りうる値: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0

​

レスポンス例

{
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  }
}

​

POST accounts/:account_id/preroll_call_to_actions

PREROLL_VIEWS ラインアイテムに対するオプションの行動喚起 (Call-to-Action、CTA) を設定します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions

​

パラメーター

Name	Description
account_id required	対象となるアカウントを識別するための識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
call_to_action required	広告内で表示されるボタンの CTA テキストです。 Type: enum Possible values: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW
call_to_action_url required	ユーザーが CTA ボタンをクリックしたときの遷移先となる URL です。 Type: string Example: https://www.x.com
line_item_id required	リクエスト内で操作対象となるラインアイテムへの参照です。 Type: string Example: 8v53k

​

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_id=8v53k&call_to_action=VISIT_SITE&call_to_action_url=https://www.x.com

​

レスポンス例

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "8v53k",
      "call_to_action": "VISIT_SITE",
      "call_to_action_url": "https://www.x.com",
      "account_id": "18ce54d4x5t"
    }
  }
}

PREROLL_VIEWS ラインアイテムのオプションのコールトゥアクション (CTA) を更新します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

パラメーター

Name	Description
account_id 必須	レバレッジドアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常、必須パラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t
preroll_call_to_action_id 必須	リクエスト内で操作対象となる preroll CTA を参照するための値です。 種別: string 例: 8f0
call_to_action 任意	広告内で表示されるボタンの CTA テキストです。 種別: enum 取りうる値: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW
call_to_action_url 任意	CTA ボタンがクリックされたときにユーザーをリダイレクトする URL です。 種別: string 例: https://www.x.com

​

リクエスト例

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW

​

レスポンス例

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "WATCH_NOW",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-09-09T05:51:26Z",
    "deleted": false
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "call_to_action": "WATCH_NOW",
      "account_id": "18ce54d4x5t"
    }
  }
}

現在のアカウントに属する指定のプレロールのコールトゥアクション (CTA) を削除します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

パラメーター

Name	Description
account_id required	レバレッジドアカウントの識別子です。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須となるパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
preroll_call_to_action_id required	リクエスト内で操作対象となるプレロール CTA (Call To Action) を参照するための ID です。 Type: string Example: 8f0

​

リクエスト例

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0

​

レスポンス例

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-08-30T06:08:21Z",
    "deleted": true
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  }
}

​

スケジュール済みツイート

​

GET accounts/:account_id/scheduled_tweets

現在のアカウントに関連付けられている予約ツイートの一部またはすべての詳細を取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets

​

Parameters

Name	Description
account_id 必須	レバレッジドアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
count 任意	個々のリクエストごとに取得するレコード数を指定します。 型: int 既定値: 100 最小値/最大値: 1 / 200
cursor 任意	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 型: string 例: c-j3cn6n40
user_id 任意	予約ツイートを取得する対象ユーザーを指定します。指定しない場合は、そのアカウントの FULL プロモート可能ユーザーが既定値になります。 型: long 例: 756201191646691328

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?count=1

​

レスポンス例

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name": "test name",
      "completed_at": "2017-06-18T22:00:05Z",
      "text": "あなたがいたい場所",
      "user_id": "756201191646691328",
      "scheduled_status": "SUCCESS",
      "id": "875828692081037312",
      "nullcast": true,
      "created_at": "2017-06-16T21:33:27Z",
      "scheduled_at": "2017-06-18T22:00:00Z",
      "card_uri": null,
      "updated_at": "2017-06-19T18:02:20Z",
      "tweet_id": "876560168963645440",
      "media_keys": []
    }
  ],
  "next_cursor": "c-j41uw400"
}

現在のアカウントに関連付けられている特定の予約ツイートを取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

パラメーター

Name	Description
account_id required	対象のアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
scheduled_tweet_id required	リクエストで操作するスケジュール済みツイートを指す識別子です。 Type: string Example: 917438609065623552

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552

​

レスポンス例

{
  "request": {
    "params": {
      "scheduled_tweet_id": "917438609065623552"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

​

POST accounts/:account_id/scheduled_tweets

アカウントの完全なプロモーション対象ユーザー (デフォルト) 、または as_user_id パラメーターで指定されたユーザーとして予約ツイートを作成します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets

​

パラメーター

名前	説明
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
scheduled_at required	ツイートが公開される時刻を ISO 8601 形式で指定します。 Note: ツイートをスケジュールできるのは、最大で 1 年先までです。 Note: ツイートは分単位の粒度でのみスケジュールしてください。秒は無視されます。 Type: string Example: 2017-12-31T23:59:00Z
as_user_id required	ツイートを代理投稿する広告主のユーザー ID です。広告主は、ads.x.com からあなたのハンドル (または複数のハンドル) に対して、自分の広告アカウントへのアクセス権を付与する必要があります。この権限により、広告主のハンドルではなく、自分自身のハンドルの OAuth トークンを使って API を呼び出すことができます。 Type: long Example: 756201191646691328
text sometimes required	ステータス更新のテキストです。media_keys が指定されていない場合は必須です。 Type: string Example: just setting up my twttr
card_uri optional	利用可能な場合、任意のカードレスポンスで返される card_uri の値を使用してツイートにカードを関連付けます。 Type: string Example: card://855591459410511943
media_keys optional	カンマ区切りの識別子リストを指定して、ツイートにメディアを関連付けます。最大で画像 4 枚、アニメーション GIF 1 件、または動画 1 件を含めることができます。 Note: メディアアセットは、そのアカウントの Media Library 内に存在している必要があります。 Type: string Example: 13_1153584529292270722
nullcast optional	nullcast (「Promoted-only」) ツイートを作成するかどうかを指定します。 Type: boolean Default: true Possible values: true, false
name optional	スケジュール済みツイートの名前です。最大 80 文字。 Type: string Example: Tweet with name

​

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?as_user_id=756201191646691328&media_keys=3_917438348871983104&scheduled_at=2018-01-01

​

レスポンス例

{
  "request": {
    "params": {
      "media_keys": [
        "3_917438348871983104"
      ],
      "scheduled_at": "2018-01-01T00:00:00Z",
      "as_user_id": 756201191646691328
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

現在のアカウントの指定された予約ツイートを更新します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

パラメータ

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須となるパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
scheduled_tweet_id required	リクエストで操作する予約ツイートを指定します。 Type: string Example: 870321875435442177
card_uri optional	利用可能な場合、任意の card レスポンスの card_uri 値を使用してツイートに card を関連付けます。 Note: 値を指定せずにパラメータのみを指定すると、未設定 (削除) されます。 Type: string Example: card://875146925316386347
media_keys optional	カンマ区切りの識別子のリストを指定して、ツイートにメディアを関連付けます。画像は最大 4 枚、アニメーション GIF は 1 つ、または動画は 1 つまで含めることができます。 Note: メディアアセットはアカウントの Media Library に存在している必要があります。 Note: 値を指定せずにパラメータのみを指定すると、未設定 (削除) されます。 Type: string Example: 13_1153584529292270722
nullcast optional	ツイートを nullcast (「Promoted-only」) として作成するかどうかを指定します。 Type: boolean Possible values: true, false
scheduled_at optional	ツイートを公開 (または配信開始) する時刻を、ISO 8601 形式で指定します。 Type: string Example: 2017-12-31T23:59:59Z
text optional	ステータス更新の本文。 Type: string Example: just setting up my twttr
name optional	予約ツイートの名前。最大 80 文字。 Type: string Example: Tweet with name

​

リクエスト例

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice

​

レスポンスの例

{
  "request": {
    "params": {
      "scheduled_tweet_id": "875057751231037440",
      "text": "winter solstice"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "SCHEDULED",
    "text": "winter solstice",
    "user_id": "756201191646691328",
    "id": "875057751231037440",
    "nullcast": true,
    "created_at": "2017-06-14T18:30:00Z",
    "scheduled_at": "2017-12-21T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T18:30:00Z",
    "tweet_id": null,
    "media_keys": []
  }
}

現在のアカウントに紐づく指定した予約済みツイートを完全に削除します。

注: これは復元できない完全削除 (ハード削除) です。そのため、削除された予約済みツイートを取得することはできません。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

パラメーター

Name	Description
account_id required	対象となるアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで、通常必須パラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
scheduled_tweet_id required	このリクエストで操作対象となる Scheduled Tweet への参照。 Type: string Example: 870321875435442177

​

リクエスト例

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776

​

レスポンス例

{
  "request": {
    "params": {
      "scheduled_tweet_id": 875064008595787776
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "DELETED",
    "text": "こんにちは、世界",
    "user_id": "756201191646691328",
    "id": "875064008595787776",
    "nullcast": true,
    "created_at": "2017-06-14T18:54:52Z",
    "scheduled_at": "2017-06-15T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T19:01:16Z",
    "tweet_id": null,
    "media_keys": []
  }
}

​

ツイートプレビュー

​

GET accounts/:account_id/tweet_previews

公開済み、予約済み、または下書きのツイートをプレビューします。

• 1 回の API リクエストで 最大 200 件 までの複数ツイートをプレビュー可能
• ツイートのレイアウトとスタイルを正確かつ最新の状態でレンダリング
• 最新のフォーマットおよびカード type をすべてサポート
• iframe を返します

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/tweet_previews

​

Parameters

Name	Description
account_id required	利用対象アカウントの識別子。このリソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
tweet_ids required	識別子をカンマ区切りで並べたリスト。最大 200 個の ID を指定できます。 Note: ID は指定した tweet_type に対応している必要があります。たとえば、予約ツイートの ID を渡し、かつ tweet_type=PUBLISHED を指定した場合、その ID のプレビューは返されません。 Type: long Example: 1122911801354510336,1102836745790316550
tweet_type required	指定した tweet_ids に対するツイートの種別。 Type: enum Possible values: DRAFT, PUBLISHED, SCHEDULED

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet_previews?tweet_ids=1122911801354510336,1102836745790316550&tweet_type=PUBLISHED

​

レスポンス例

{
  "request": {
    "params": {
      "tweet_ids": [
        "1122911801354510336",
        "1102836745790316550"
      ],
      "tweet_type": "PUBLISHED",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "tweet_id": "1122911801354510336",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAANVYW2%2FbNhT%2BKwJf59iiZDuSgWLI0suyrUXbZBuGaiAoibbZUKRGUk7TIP99h6Jsy4mdC5CX%2BiUiz%2F0cfueQuUH2ijGLZsENKjSjlpWEwhK9VzI4qXUQpQE%2BnuF4FofBTyH8gijEKRogXqIZxlGUYpyEOJ6MJziM46kjEGM1qNhDBbl5IwSx7JszsuIlU8EVyw23DGhWN7JwPqDZnArDBqjkphb0uhUgmsoFQ7Mv4QDH%2Fw4Qk5Zbzgya3aAlNUtLF%2FD9BSjmusqV6BaNYZpUjlnJ9Zb2xFtgVY0uQCnKmjCMCxosNZu%2FytDS2trMslE2oqU5ojUf2ituLdPDQlUZCjQTwCXVXAmhrjIvzi48T3BSmuBUVbUC214x6PEsLnWSaFYLiEpBqqhtDHHZlJCZA0Sf0fsMbWz7ZTvSIUkD1WaSSFqxNdlJuFw6fceTKdQZp3g6nk5THEdJr7D3iRCU14ROPp4F74sLZuycFi7YHUMIElkVdksVCuoNhQHSOZXBWyhxwU2hBsHpCWoLtfauZKCJ1x3zmbQqcHq4XARUlgHYNSBQa2VZ0T9BvkBMG1KoRsKpO8KwqTmT5c6W4MYd%2Fm7H29xBxMWyCX5rRBDhACezyXQWJVtEtCebruAwwUne0dvYgqj53LCNVssrRr4ruUn8ginCJM1Fz%2B0V03zOexv%2BLOzqFgAI8IxJsF4oaTXPG6sg1LvauCEWUmsEBfK%2BXcjqPSHI5ZwLRnJaXC40WHXZEU4ehe0P7eXhFV0w0lauRZEHUW4cgKpFC59Ry2OykV2yavMXZ6N8MawhpIf1khabnXbzUuotrO%2BFvjeWetfYDi8YA3TE4yTGx%2BNJMgnTJJpko9cXvxefT%2BtzIpWuqBh%2BrftePBTZixvLqZTQGbYxPWjHc3tDdzCfjfAYvqbROMY9%2FYLLy8PnxEDHz6kmudIlePEoHyzEYa52KhykAlrunZ%2FtYGFz2ghLOuZD%2B3ekfDPhDnUeun4D2up%2FDTQjYti2eUhlAcG%2BvZkN9jcoJPa6dh1RukZw2zaBTdtRkB0uofVs5GAIFmxL30J9vadZO8jX3SH07ch1oz1bW4x3Yn3UK2N4DkMCYoGxzFfb6KEv137cbppqRwP%2FC6pLR%2BoafTRJpnEaHuPpDFJZKdLOerKd9f4AOqn2%2FOFwPI5DHKZpGOPpJBmnrqU6cpuouxh0hCNHOALCETdHJas1a%2B8OQy5XVMAQG6CcS8jjgsC68Y539olZKm2ZhN7eKr5BXTXOLz6ffXjnxhZkeC25AxQLAMlG32nJ%2Fjz%2F6zVOXO1cQaDypGy0b6WGwVZpnqA4GjsF7o4DcLjipV0%2BQQjGzVZobZyXT5GMSQroPR5HyRiuZfAVJWFP2ZLxxdI%2BQVHqhFZUcnv9xBSWbMUEHCDdv0k5LeualA5Bzy3HQa1dQOpKdlekR5Xuudb0EiPMs31rj3y%2Fq9KqFnx%2B7bGQje5XAhqvyEbmk%2F7FvEmrt6sPrE5Pvw2ruEl%2Bhuvtq8h5BLde17AedeT1OjXBR%2Bg4cxgG%2FWy%2FdKJBkNHqxXO0qmi9L1NDR%2BiZ9zPUwLzr2z97f%2FLujbtxt9TO%2Bg16ZPjtuEDssqny%2FcUCiWz0T56%2F%2B%2FTr6u%2FPX9Xbhf7jezdvOyxjYBygNayOI1hQ0c2I2zvu%2F7COE0H1j%2Bz%2Btx8wgHY0Pnt49aDbPs14zsglu%2B4mcatvo7xedw2w0P%2BGTsAL1pv18No9qTlqHy3Gv89w7LBJmxLeWTu8cBkom6J9xcF8bopLtonJGd6%2BaG4HAWpvDv5VJv2%2FDIKbzSYsrG7Y7e3%2FCm%2FIC8QQAAA%3D'>"
    },
    {
      "tweet_id": "1102836745790316550",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAO1YbW%2FbNhD%2BK4K%2Bzo3eZdlAMQQttqZrt6FNEXRVIVASJTOhSIWkHDeB%2F%2FuOomXLb%2BuHdQWGzV8s3T13vCOPz539ZKsHjJU9t57sQmCkcJkheLWvO2y9RcJyI8udzkN%2F7ofWDy58LN%2F1ZvbEJqU99zzXT4J4GkbTmRt4cRS5WpFJJcDFCS3YVR2lmcIrvcgNWmJpLZRq5Tx1UkddFDx16mUU8Lv4UhQAV6JjhQ7LnleISjyxSyJbir70PjKBWI3t%2BSd3En2e2JgpogiW9vzJXiC5UKiG50%2BgkV%2BanNPNSyexyBoN5mwQiUHZ4JIgeHwyGbpumLjh1PcDfxZ6XpSE4wyPtXpnWEkKHcSneOLPBpcZLAEmOtk%2B1zaXF%2BqBNDXk3KSOTkY9ZEtSYp6pRdfkqXPCPdh1qQNWYPFz%2BfHls7v7y6s3dZm%2Fci9u29oeLZb1%2B7pZUv6ja%2B5SO3uOw6kZaEsKHYhSWJhQ9rB41SJWQiUe%2BR2boJY0hcJSVajAqSMVUp2EBI6rLnX6FEGnC%2BpLi3UEC644vEryaOqlz18%2FPMCp6zpebL4F1hgwKQRv7bXZ4a4ZoL5rsPE0GmErojRUNojSDTJODDBIgmMgRULX8cblBjn13UMkQCu4pZ3og16vP6%2F1dincb9e4%2FP8v4%2F9EGfeSf2UZm%2BMirOIaj2SLC03nwMlQcV480RVXdr2AZQ2hlEhdx9MYnC2RIIgp2dd3ThSgwHUSQBKgLTiDCwE1Mdqi1Gna8MQR98pzxfQXZQT61IlDdxXEcC7Rm1fsHl96H8sau%2Fer1xew2I%2FQfJ4HsCmjCP0o%2Fr4Rwo6svAQivLvqXn14mRD%2FD%2BnWuX91NkJv%2Bp1D1GWyghJJnbD56HePt%2FjXG%2FJbVd3cHsR4EBFqW0qKvjxSZ%2FWsaXH94d2bbxhdS1Nn5r17CF7cTMurt6%2Ffh7fJRRN0yRDT5wMyntioLIkOCNHM8NdQ3sDLVAetGQTLQpBWw4wANzkuS5RrAEw7MOE0nGFFHo2on3oM0UveiUK7STvXDQpkLQSunqejXFEp9wjJtgSmgGC84pTyh9SY4muDsS5LaXyBqdH0xJ8J3FKYsHhm6CjTPYTB4HZGafrIMaAftE7bblTnLGGPMGYZQw0e1NpC76X2N41iGEO9mReHcTzzAj8ZtbNjJSRlPNmXv19Zb4vrDd1q4hwvZO%2BRMWgpNxUGqveIWT%2FBuFkQWfCJ9eJyKDUT3f6xXjHFLe2HsNqCJmDBuhIMWsEV8NxomjXngoXMCt4xGIqfeSAUBDr6ngjoT8%2FmG4lZc39gX3TW645avmd5yTyK536yG9hjPXijJdQPgajGfjtVZLyqJN56VaTB2SOU4CCogacx09W4C3uJBanISGBqYd83heEcIsPMNnwiSN4pDqkeeiMyA%2F5hkiJQn5LqHnBoBHtZEYqzHBV3tYBV9e5QbW%2B7%2Fcc%2BiSENqvHhFIP2J4oeA01YLXCz%2FfZSJ68vWlZ%2Fxe%2BJgeUbuFdkSwY7%2FclcDqajPSwsBrcjCJPAg8kiidxZ4kep8%2FL6l%2BLdi%2FZ9xriAVr8Zh45W%2Bfoo9vcXyxFjwAyHJH5mHYM2Cx3ceWD2EJ5iPwy8kX9K2N35OpHQE3IkspyLEqL4Kg5e6HlU%2Fwv1rBZuy1H97H7k4gp1VGUb8Dn5gZUhE6Jvnbm6RgC0et8BGWUS78iDcQU32NCb3N797S0c2izTRLDuSWBLOxx2hzCgnq0dzMQF3ul3V32QCdz%2FzzCwg2voSLPRCdHujm%2FMxreeS0lyaBKQi4Rmu9xlD7zcmiF4S6pD%2Bxxz0Xpi6TNouOFTZv6LsJ62QnjRfXi9%2FhONbe6QHREAAA%3D%3D'>"
    }
  ]
}

​

ツイート

​

GET accounts/:account_id/tweets

アカウントのフルプロモーション可能ユーザー (デフォルト) または user_id パラメータで指定されたユーザーのツイート詳細を取得します。指定できるのは、そのアカウント配下のプロモーション可能ユーザーのいずれかです。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/tweets

​

パラメーター

Name	Description
account_id required	レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
tweet_type required	指定された tweet_ids に対するツイートの種類。 Type: enum Possible values: DRAFT, PUBLISHED, SCHEDULED
count optional	各リクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	結果の次のページを取得するためのカーソルを指定します。詳細については Pagination を参照してください。 Type: string Example: AAAAAFhLRpQLNF-sGBSgAA
include_mentions_and_replies optional	取得可能なツイートの一覧からメンションおよび返信を除外するかどうか。 Type: boolean Default: false Possible values: true, false
name optional	ツイートを name で絞り込むための任意のクエリ。このパラメーターを省略すると、すべてを取得します。最大長: 80 文字。 Note: 大文字と小文字を区別しない前方一致で検索を行います。 Type: string Example: dtc
timeline_type optional	nullcast (別名「Promoted-only」) ツイート、オーガニックツイート、またはその両方を返すかどうか。 Type: enum Default: NULLCAST Possible values: ALL, NULLCAST, ORGANIC
trim_user optional	ツイートのレスポンスから user オブジェクトを除外するかどうか。有効にした場合、返される user オブジェクトの内容は、そのツイートの作成者のユーザー ID のみになります。 Type: boolean Default: false Possible values: true, false
tweet_ids optional	識別子のカンマ区切りリスト。最大 200 個の ID を指定できます。 Note: ID は指定された tweet_type に対応している必要があります。たとえば、予約済みツイートの ID を渡す場合、そのツイートがレスポンスで返されるためには、tweet_type を SCHEDULED に しなければなりません。 Type: long Example: 1122911801354510336,1102836745790316550
user_id optional	ツイートの対象とするユーザーを指定します。設定しない場合は、そのアカウントの FULL promotable user がデフォルトになります。 Type: long Example: 756201191646691328

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets?tweet_ids=1166476031668015104&tweet_type=PUBLISHED&trim_user=true

​

レスポンス例

{
  "request": {
    "params": {
      "tweet_ids": [
        "1166476031668015104"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "name": null,
      "source": "<a href="https://ads-api.x.com" rel="nofollow">Ads API Internal Test App</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        9
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1166476031668015104",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "id": 1166476031668015104,
      "in_reply_to_status_id": null,
      "conversation_settings": "EVERYONE",
      "nullcast": true,
      "created_at": "Tue Aug 27 22:22:12 +0000 2019",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "hello, v6",
      "lang": "es",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1166476031668015104"
    }
  ]
}

​

POST accounts/:account_id/tweet

アカウントのフルプロモータブルユーザー (デフォルト) または as_user_id パラメーターで指定したユーザーとしてツイートを作成します。nullcast (デフォルト) およびオーガニックなツイートの作成の両方をサポートします。nullcast されたツイートはパブリックタイムラインには表示されず、フォロワーにも配信されません。いずれのタイプもキャンペーンで使用できます。

認証済みユーザーがこのアカウントの FULL プロモータブルユーザーでない場合は、GET accounts/:account_id/authenticated_user_access エンドポイントにリクエストを送信して、このユーザーとしてツイートを作成する権限があるかどうかを確認してください。TWEET_COMPOSER 権限が付与されている場合、そのユーザーはこのエンドポイントを使用して、FULL プロモータブルユーザー の代わりに nullcast されたツイートを作成できます。

メディアに upload.x.com エンドポイント を使用する場合は、このエンドポイントに渡す as_user_id の値と同じ user_id の値を、additional_owners パラメーターに指定してください。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/tweet

​

Parameters

Name	Description
account_id required	利用するアカウント (leveraged account) の識別子。この値はリソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須となるパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
as_user_id required	ツイートを代理で投稿する広告主のユーザー ID。広告主は、ads.x.com を通じて、自身の広告アカウントへのアクセス権をあなたのハンドル (または複数のハンドル) に付与する必要があります。この権限により、広告主のハンドルではなく、あなた自身のハンドルの OAuth トークンを使用して API を呼び出すことができます。 Type: long Example: 756201191646691328
text sometimes required	ステータス更新のテキスト。media_keys が指定されていない場合は必須です。 Type: string Example: hello, world
card_uri optional	利用可能な場合、任意の Cards レスポンスの card_uri 値を使用して、このツイートにカードを関連付けます。 Type: string Example: card://853503245793641682
conversation_settings optional	このツイートに誰が返信できるかを選択します。メンションされたユーザーは常に返信できます。 Note: このフィールドは POST リクエストのレスポンスでは返されませんが、GET リクエストを行った場合には返されます。 Note: このパラメータが機能するのは Ads API v8 以降のみです。 Type: enum Default: EVERYONE Possible values: EVERYONE, FOLLOWING, MENTIONED_USERS
media_keys optional	識別子のカンマ区切りリストを指定して、このツイートにメディアを関連付けます。画像は最大 4 枚、アニメーション GIF は 1 つ、または動画は 1 つまで含めることができます。 Type: string Example: 13_1153584529292270722
name optional	ツイートの名前。最大文字数: 80 文字。 Type: string Example: Tweet with name
nullcast optional	nullcast (「Promoted-only」) ツイートを作成するかどうか。 Note: オーガニックツイート (nullcast=false) は、認証済みユーザーに対してのみ作成できます。 Type: boolean Default: true Possible values: true, false
trim_user optional	ツイートレスポンスに user オブジェクトを含めないかどうか。有効にすると、返される user オブジェクトはツイート投稿者のユーザー ID のみになります。 Type: boolean Default: false Possible values: true, false
tweet_mode optional	レスポンスを互換モードにするか拡張モードにするかを指定します。詳細はこちらを参照してください。 Type: string Possible values: compat, extended
video_cta optional	動画の CTA。 Type: enum Possible values: VISIT_SITE, WATCH_NOW
video_cta_value optional	動画の該当 CTA に設定する値。 Type: string Example: https://dev.x.com
video_description optional	動画の下に表示される説明文。最大文字数: 200 文字。 Type: string Example: X 広告プラットフォームと連携
video_title optional	動画の下に表示されるタイトル (見出し) 。最大文字数: 70 文字。 Type: string Example: X Ads API

​

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet?text=hello, world&as_user_id=756201191646691328&trim_user=true

​

レスポンス例

{
  "data": {
    "created_at": "Sat Jun 24 05:08:30 +0000 2017",
    "id": 878479925472251906,
    "id_str": "878479925472251906",
    "text": "hello, world",
    "name": null,
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "<a href='"https://ads-api.x.com"' rel='"nofollow"'>Ads API Internal Test App</a>",
    "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": null,
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "hello, world",
      "trim_user": true,
      "as_user_id": 756201191646691328,
      "account_id": "18ce54d4x5t"
    }
  }
}

現在のアカウントに属する指定したツイートの name を更新します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/tweets/:tweet_id/name

​

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須となるパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
tweet_id required	リクエスト内で操作対象となるツイートを参照するための値です。 型: long 例: 994747471329873920
name optional	ツイートの名前です。最大長: 80 文字。 型: string 例: Tweet with name

​

リクエスト例

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets/994747471329873920/name?name=new Tweet name

​

レスポンス例

{
  "request": {
    "params": {
      "tweet_id": 994747471329873920,
      "name": "new Tweet name",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
      "coordinates": null,
      "retweeted": false,
      "name": "new Tweet name",
      "conversation_settings": "EVERYONE",
      "source": "<a href="https://ads-api.x.com" rel="nofollow">Ads API Internal Test App</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        5
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "994747471329873920",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 994747471329873920,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Wed Jan 01 00:00:00 +0000 2020",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "hello",
      "lang": "en",
      "contributors": null,
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "utc_offset": null,
        "name": "Tushar Bhushan",
        "friends_count": 1065,
        "screen_name": "imit8me",
        "location": "San Francisco, CA",
        "protected": false,
        "url": "https://tushdante.github.io",
        "profile_image_url": "http://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_background_color": "C0DEED",
        "profile_use_background_image": true,
        "is_translator": false,
        "geo_enabled": true,
        "description": "Open Sorcerer / Partner Engineer @twitter / Space Traveller | Former evangelist @sendgrid @keen_io",
        "profile_link_color": "1DA1F2",
        "id_str": "3271358660",
        "listed_count": 31,
        "default_profile_image": false,
        "followers_count": 407,
        "profile_image_url_https": "https://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_sidebar_border_color": "C0DEED",
        "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png",
        "favourites_count": 5993,
        "following": null,
        "default_profile": true,
        "withheld_in_countries": [],
        "id": 3271358660,
        "profile_background_tile": false,
        "contributors_enabled": false,
        "follow_request_sent": null,
        "created_at": "Tue Jul 07 22:34:58 +0000 2015",
        "profile_sidebar_fill_color": "DDEEF6",
        "translator_type": "regular",
        "lang": null,
        "profile_text_color": "333333",
        "notifications": null,
        "verified": false,
        "time_zone": null,
        "profile_banner_url": "https://pbs.twimg.com/profile_banners/3271358660/1474853576",
        "statuses_count": 500,
        "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png",
        "is_translation_enabled": false
      },
      "tweet_id": "994747471329873920"
    }
}

​

動画会話カード

注意: カードをツイートと関連付けるには、card_uri パラメータを指定し、POST accounts/:account_id/tweet、POST statuses/update、または POST accounts/:account_id/scheduled_tweets のいずれかのエンドポイントを呼び出してください。

​

GET accounts/:account_id/cards/video_conversation

現在のアカウントに関連付けられている一部またはすべての Video Conversation Card の詳細情報を取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation

​

パラメータ

Name	Description
account_id required	レバレッジドアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須となるパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを目的の video conversation card のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 5a86h
count optional	個々のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
q optional	name によってカードを絞り込むためのオプションのクエリです。すべてを取得する場合はこのパラメータを省略します。最大長: 80 文字。 Note: 大文字と小文字を区別しない前方一致でマッチングを行います。 Type: string Example: night sky
sort_by optional	サポートされている属性を指定して、昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果もレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメータと cursor は同時に使用できません。 Note: total_count を含むリクエストには、現在 15 分あたり 200 に設定された、より厳しいレート制限が適用されます。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?card_ids=5a86h

​

レスポンス例

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_ids": [
        "5a86h"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "id": "5a86h",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "created_at": "2018-01-30T17:53:04Z",
      "card_uri": "card://958397665015775232",
      "title": "Developers",
      "updated_at": "2018-01-30T17:53:04Z",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "deleted": false,
      "card_type": "VIDEO_CONVERSATION"
    }
  ]
}

現在のアカウントに紐づく特定の Video Conversation Card を取得します。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id

​

パラメーター

Name	Description
account_id required	レバレッジドアカウント (leveraged account) の識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_id required	リクエスト内で操作対象となる video conversation card への参照です。 Type: string Example: 4i0ya
with_deleted optional	削除済みの結果をリクエストに含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h

​

レスポンス例

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_id": "5a86h",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  }
}

​

POST accounts/:account_id/cards/video_conversation

指定したアカウントに関連付けられた新しい Video Conversation カードを作成します。

エンドポイントへのメディアのアップロードに関する役立つ情報については、Uploading Media を参照してください。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation

​

パラメータ

名前	説明
account_id 必須	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
first_cta 必須	最初のオプションのCall-To-Action (CTA)用ハッシュタグ。最大長は20文字 (#はカウントに含めません) 。 Type: string Example: #APIs
first_cta_tweet 必須	最初のCTAがクリックされたときに使用されるツイート本文。 Type: string 例: Ads API
media_key 必須	このカードで使用する動画のメディアキー。 注: 動画はアカウントのMedia Libraryに登録されている必要があります。 注: アスペクト比は16:9である必要があります。 Type: string Example: 13_1168079965037467209
name 必須	カード名。 Type: string Example: video conversation card
thank_you_text 必須	CTA ボタンがクリックされた後に表示されるテキストです。最大長: 23文字。 Type: string Example: Build it
title 場合によっては必須	カードのタイトルで、動画の下部かつ CTA の上に表示されます。最大文字数: 23 文字。 Type: string Note: second_cta が設定されていない場合に必須です。 Example: Developers
second_cta 場合によっては必須	2つ目のオプション用のCTA (Call-To-Action) ハッシュタグ。最大長: 20文字 (#は含みません) 。 Type: string 注: title が設定されていない場合は必須です。 例: #ShareAgain
second_cta_tweet 条件付き必須	2番目のCTAがクリックされたときに使用されるツイート本文。 注意: second_cta が設定されている場合に必須です。 Type: string 例: I Heart @AdsAPI Again
poster_media_key 任意	このカードで使用されるポスター画像のメディアキー。指定しない場合、動画の最初のフレームが使用されます。 注意: 動画はアカウントの Media Library に登録されている必要があります。 型: long 例: 3_882726458191298561
third_cta 任意	3 番目のオプションで使用する Call-To-Action (CTA) 用のハッシュタグ。最大文字数: 20 文字 (「#」は含めない) 。 Type: string Example: #ShareMore
third_cta_tweet 条件付き必須	3番目のCTAがクリックされたときに使用されるツイート本文。 Type: string 注: third_cta が設定されている場合は必須です。 例: I Heart @TwitterDev
fourth_cta 任意	4 番目のオプションの Call-To-Action (CTA) 用ハッシュタグ。最大長: 20 文字 (# を含めない) 。 Type: string 例: #ShareExtra
fourth_cta_tweet 条件付き必須	4 番目の CTA がクリックされたときに使用するツイート本文。 Type: string 注: fourth_cta が設定されている場合は必須です。 Example: I Heart @TwitterDev Again
thank_you_url 省略可能	お礼メッセージに合わせて表示するURL。 Type: string Example: https://example.com/thankyou
unlocked_image_media_key 省略可	インスタントアンロックシナリオで使用する画像の media_key。このフィールドは書き込み専用フィールドです。レスポンスでは、この画像に対する X の URL が API から返されます。 注: 画像はアカウントのメディアライブラリに登録されている必要があります。 Type: string Example: 3_883112887618682880
unlocked_video_media_key 任意	GET accounts/:account_id/media_library エンドポイントで取得した動画の識別子で、Instant Unlock シナリオで使用されます。 型: string 例: 13_867520357225418752

​

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?first_cta=#APIs&first_cta_tweet=Ads API&name=video conversation card&thank_you_text=Build it&title=Developers&media_key=13_958388276489895936

​

レスポンス例

{
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "video_poster_height": "9",
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "account_id": "18ce54d4x5t",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "title": "Developers",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "video_poster_width": "16",
      "card_type": "VIDEO_CONVERSATION"
    }
  }
}

現在のアカウントに紐づく、指定した Video Conversation Card を更新します。

当社のエンドポイントに画像をアップロードする際に役立つ情報については、Uploading Media を参照してください。

​

リソース URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id

​

パラメーター

名前	説明
account_id 必須	利用対象のアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメータとなります。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
card_id 必須	リクエストで操作している Video Conversation Card への参照。 Type: string Example: 5a86h
first_cta 省略可能	最初のオプションで使用する Call-To-Action (CTA) のハッシュタグ。最大長：20文字 (#は文字数に含めません) 。 Type: string Example: #APIs
first_cta_tweet 任意	最初のCTAがクリックされたときに投稿されるツイート本文。 Type: string Example: Ads API
second_cta 任意	2つ目のオプション用のコールトゥアクション (CTA) ハッシュタグ。最大長: 20文字 (#は含めない) 。 Type: string 注: title が設定されていない場合は必須。 Example: #ShareAgain
second_cta_tweet 任意	2 番目の CTA がクリックされたときに使用するツイート本文。 注: second_cta が設定されている場合は必須です。 Type: string 例: I Heart @AdsAPI Again
third_cta 任意	3 番目のオプションの Call-To-Action (CTA) 用ハッシュタグ。最大文字数: 20 文字 (# 記号は文字数に含めません) 。 Type: string Example: #ShareMore
third_cta_tweet 任意	3 番目の CTA がクリックされたときに使用するツイート本文。 Type: string Note: third_cta が設定されている場合は必須です。 Example: I Heart @TwitterDev
fourth_cta 任意	4 番目のオプション用の Call-To-Action (CTA) ハッシュタグ。最大 20 文字 (# は含めません) 。 Type: string Example: #ShareExtra
fourth_cta_tweet 任意	4 番目の CTA がクリックされたときに使用するツイート本文。 Type: string Note: fourth_cta が設定されている場合は必須です。 Example: I Heart @TwitterDev Again
media_key 任意	このカードで使用する動画の media key。 注意：動画はアカウントの Media Library に登録されている必要があります。 注意：アスペクト比は 16:9 である必要があります。 型: string 例: 13_1168079965037467209
name 任意	カード名。 Type: string 例: developers card
poster_media_key 任意	このカードで使用するポスター画像の media key です。指定しない場合は動画の先頭フレームが使用されます。 注: 動画はアカウントの Media Library に保存されている必要があります。 Type: long Example: 3_882726458191298561
thank_you_text 任意	CTA がクリックされた後に表示されるテキスト。最大 23 文字。 Type: string Example: Build it
thank_you_url 任意	お礼テキストと共に表示される URL。 Type: string Example: https://example.com/thankyou
title 任意	動画の下部とCTAの上に表示されるカードのタイトルです。最大長: 23文字。 Type: string 注記: second_cta が設定されていない場合は必須です。 例: Start a conversation
unlocked_image_media_key 任意	インスタントアンロックシナリオで使用される画像の media_key。 これは書き込み専用のフィールドです。レスポンスでは、この画像用の X URL を API が返します。 Note: 画像はアカウントのメディアライブラリに登録されている必要があります。 Type: string Example: 3_883112887618682880
unlocked_video_media_key 任意	インスタントアンロックシナリオで使用される、GET accounts/:account_id/media_library エンドポイントから取得した動画の識別子。 Type: string Example: 13_867520357225418752

​

リクエスト例

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h?name=developers card

​

レスポンス例

{
  "data": {
    "name": "developers card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T18:02:15Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "VIDEO_CONVERSATION",
      "card_id": "5a86h",
      "name": "developers card"
    }
  }
}

現在のアカウントに属する指定の Video Conversation Card を完全に削除します。

注: これはハードデリート (完全削除) です。そのため、削除されたカードを復元することはできません。

​

リソースURL

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id

​

パラメーター

Name	Description
account_id required	レバレッジアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
card_id required	このリクエストで操作する Video Conversation Card への参照です。 型: string 例: 4i0ya

​

リクエスト例

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/4i0ya

​

レスポンス例

{
  "data": {
    "name": "video conversation card",
    "id": "4i0ya",
    "created_at": "2017-07-07T01:36:39Z",
    "updated_at": "2017-08-23T13:29:13Z",
    "deleted": true,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0ya",
      "card_type": "video_conversation",
      "account_id": "18ce54d4x5t"
    }
  }
}