> ## Documentation Index > Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # クリエイティブ export const Button = ({href, children}) => { return
; };
## 概要
クリエイティブとは、キャンペーンでプロモーションできるあらゆるエンティティを指します。投稿にはテキスト、画像、GIF、動画、またはカードを含めることができます。カードには画像または動画を含めることができます。 画像、GIF、または動画クリエイティブは、[POST media/upload](/ja/x-api/media/upload-media#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](/ja/x-ads-api/creatives#cards-2) で使用されるアセットに適用されます。画像は 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](/ja/x-ads-api/creatives#cards-2) で使用されるアセットに適用されます。サポートされているアスペクト比 (横:縦) は次のとおりです。 * 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 は、[ツイート内](/ja/x-ads-api/creatives#tweets-2)および次のカードでのプロモート動画をサポートしています。 * [Video Website](https://devcommunity.x.com/t/ads-api-version-11/168814) * [Video App Download](https://devcommunity.x.com/t/ads-api-version-11/168814) * [Video Conversation](/ja/x-ads-api/creatives#video-conversation-cards) まず、[POST media/upload (chunked)](https://developer.x.com/en/docs/media/upload-media/api-reference/post-media-upload-init.html) エンドポイントを使って動画をアップロードします。`media_id` を使用して、POST accounts/:account\_id/videos エンドポイントで動画を広告アカウントに関連付けます。動画の `id` (`media_key` と呼ばれることもあります) は、その後のリクエストで使用されます。これは、整数で始まり、その後にアンダースコアが続き、末尾が長い数値になる文字列です。例としては次のような形式です: `13_875943225764098048`。 ツイートを作成するには、動画の `id` とあわせて [POST accounts/:account\_id/tweet](/ja/x-ads-api/creatives#get-accounts-account-id-tweets) エンドポイントを使用します。このステップでは、動画のタイトル、説明文、コールトゥアクション (CTA) も指定できます。これらの値はユーザーに表示されます。 Video App Download カードおよび Video Conversation カードでは、ポスター画像を追加できます。これらのカードで使用する画像は、[POST media/upload](https://developer.x.com/en/docs/media/upload-media/api-reference/post-media-upload.html) エンドポイントを使ってアップロードします。 次のいずれかのエンドポイントを使用してカードを作成します。 * [POST accounts/:account\_id/cards/video\_website](https://devcommunity.x.com/t/ads-api-version-11/168814) * [POST accounts/:account\_id/cards/video\_app\_download](https://devcommunity.x.com/t/ads-api-version-11/168814) * [POST accounts/:account\_id/cards/video\_conversation](https://devcommunity.x.com/t/ads-api-version-11/168814) 動画の `id` と、必要に応じて画像 (ポスター画像用) の `media_id` を使用します。 最後に、POST accounts/:account\_id/tweet エンドポイントを使用してツイートを作成します。カードは `card_uri` パラメータを使ってツイートに添付されます。
#### 一般情報
API を通じた動画アップロードに関する詳細な手順については、[Video Upload Guide](https://developer.x.com/en/docs/media/upload-media/uploading-media.html) を参照してください。 動画はプレロールアセットとしてプロモーションすることもできます。詳しい説明については、[Video Views Pre-roll Objective Guide](/ja/x-ads-api/campaign-management#video-views-preroll-objective) を参照してください。 * (2015-10-22 時点) プロモーションで使用する動画をアップロードする場合、[POST media/upload (chunked)](https://developer.x.com/en/docs/media/upload-media/api-reference/post-media-upload-init.html) エンドポイントへのすべての `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](/ja/x-ads-api/creatives#get-accounts-account-id-scheduled-tweets) (すべての予約ツイートの一覧を取得) * [GET accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/ja/x-ads-api/creatives#get-accounts-account-id-scheduled-tweets) (`id` を使用して特定の予約ツイートを取得) * [POST accounts/:account\_id/scheduled\_tweets](/ja/x-ads-api/creatives#post-accounts-account-id-scheduled-tweets) (新しい予約ツイートを作成) * [PUT accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/ja/x-ads-api/creatives#example-request-39) (既存の予約ツイートを更新) * [DELETE accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/ja/x-ads-api/creatives#example-request-40) (`id` を使用して予約ツイートを削除) * [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/ja/x-ads-api/creatives#scheduled-tweets-2) (既存の予約ツイートをプレビュー表示)
#### 予約済みプロモーションツイート
* [GET accounts/:account\_id/scheduled\_promoted\_tweets](/ja/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets) (すべての予約済みプロモーションツイートのリストを取得します) * [GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/ja/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (`id` を使用して予約済みプロモーションツイートを取得します) * [POST accounts/:account\_id/scheduled\_promoted\_tweets](/ja/x-ads-api/campaign-management#post-accounts-account-id-scheduled-promoted-tweets) (新しい予約済みプロモーションツイートを作成します) * [DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/ja/x-ads-api/campaign-management#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (`id` を使用して既存の予約済みプロモーションツイートを削除します)
#### 予約ツイートの閲覧
* [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/ja/x-ads-api/creatives#scheduled-tweets-2) (既存の予約ツイートを閲覧) 予約ツイートは「ライブ」のツイートとは別個のエンティティであるという性質上、これらのツイートを新規作成または編集する際には、2 種類の異なる検証処理が実行されます。最初の検証ルールセットは、予約ツイートの作成ステップで実行されます。
#### Scheduled Tweet Create:
* 認証済みユーザーが、指定された @handle に対してオーガニックツイートを作成するアクセス権を持っているか検証します。Promoted-Only ツイートの作成権限には、認証済みユーザーが [Tweet composer permissions](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/authenticated-user-access#get-accounts-account-id-authenticated-user-access) を持つアカウントユーザーである必要があります。 * `scheduled_at` 時刻の前後 15 分間のウィンドウ内で作成が予定されているツイートが 30 件を超えていないか検証します。`SCHEDULED_TWEET_LIMIT_EXCEEDED` エラーメッセージは、同じ将来の 15 分間の時間枠内に、予約ツイートが多すぎることを示します。広告主は、既存の予約ツイートを削除するか、`scheduled_at` の時刻を前または後ろにずらす必要があります。
#### 予約ツイートが「公開」されるとき:
* これらのバリデーションルールは scheduled\_at に設定された時刻に実行され、API で通常のツイートを作成する際に適用されるものと同一です。たとえば、予約ツイートに画像と GIF の両方が含まれている場合、その予約ツイートは公開されず、scheduled\_status は FAILED に設定されます。
#### ワークフロー
**新しい予約ツイートを作成する** 新しい予約ツイートは、[POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/scheduled-tweets#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!' ``` これにより、次のような予約ツイートが作成されます。 ```json theme={null} { "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](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweet-previews#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 ``` ```json theme={null} { "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](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/scheduled-promoted-tweets#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' ``` ```json theme={null} { "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、動画を管理できます。ライブラリ内のメディアアセットは、ツイートに利用したりカードを作成したりできます。また、同じアセットを複数の[クリエイティブ](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/overview)で再利用できるため、同一のアセットを何度もアップロードし直す必要がありません。
#### API エンドポイント
* [POST media/upload](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload#post-media-upload) (メディアをアップロードする) または[POST media/upload (chunked)](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload-init#post-media-upload-init) (メディアをアップロードする (チャンク) ) * [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives#get-accounts-account-id-media-library#post-accounts-account-id-media-library) (Media Library にメディアを追加する)
#### ライブラリへの追加
メディアをライブラリに追加するには、2段階の処理が必要です。まず、[POST media/upload](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload#post-media-upload) エンドポイント、または [POST media/upload (chunked)](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/api-reference/post-media-upload-init#post-media-upload-init) エンドポイント群のいずれかを使ってアセットをアップロードします (マルチパートアップロード処理の詳細については、[Chunked media upload](https://developer.x.com/content/developer-twitter/en/docs/media/upload-media/uploading-media/chunked-media-upload) ガイドを参照してください) 。 ``` twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media" ``` ```json theme={null} { "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](https://developer.x.com/x-ads-api/creatives#get-accounts-account-id-media-library#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" ``` ```json theme={null} { "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](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) エンドポイントで、`video_title` および `video_description` リクエストパラメータとして渡すことを想定しています。ツイートでは、このテキストが動画の下に表示されます。
#### 属性
Media Library では、media\_key という概念が正式に導入されています。これは、ライブラリ内のオブジェクトを一意に識別するための識別子です。media\_key は、13\_875943225764098048 のような形式の文字列です。これらは、すべてのカードエンドポイントで完全にサポートされています。 加えて、Media Library レスポンスには、文字列として表現される media\_id も含まれます。これは、現時点では media\_key を受け付けていないリソース、つまり [ツイート](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet)*、[ツイートプレビュー](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#get-accounts-account-id-tweet-preview)*、および [予約ツイート](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets) に対して返されます。現在、すべての場所で media\_key がサポートされるよう取り組んでいます。 aspect\_ratio 属性は GIF と動画に対して返されます。これは、特定のアスペクト比のみを受け付けるカードで使用するメディアをフィルタリングするために利用できます。 \*これらのエンドポイントでは、media\_key である video\_id パラメータをサポートしています。
#### 使用方法
このセクションでは、以下の画像をツイートで使用し、ウェブサイトカードの作成にも使用します。 ``` twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library/3_966947208837742592" ``` ```json theme={null} { "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" ``` ```json theme={null} { "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` を指定して[ウェブサイトカード](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/website#post-accounts-account-id-cards-website)を作成します。 ``` twurl -X POST -H ads-api.x.com "/11/accounts/18ce54d4x5t/cards" ``` ```json theme={null} { "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](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](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#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](https://developer.x.com/en/docs/ads/creatives/api-reference/cards-fetch.html#get-accounts-account-id-cards-all) と [GET accounts/:account\_id/cards/all/:card\_id](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/cards-fetch#get-accounts-account-id-cards-all-card-id) です。前者は card\_uri を指定してカードを取得し、後者はカードの ID を指定してカードを取得します。カードの ID は preview\_url の末尾にあります。上記の例では、ID は 68w3s です。
### メディアの特定
#### はじめに
メディア (画像、GIF、動画) はツイートやカードに追加できます。さらに、動画はプレロール用アセットとして、画像は [X Audience Platform](https://developer.x.com/en/docs/ads/measurement/overview/twitter-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](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/guides/media-library) を参照してください。広告アカウントの FULL プロモーション可能ユーザーに属するほとんどのアセットは、このライブラリで見つかりますが、いくつか例外もあります。 **メディアの取得** 前述のとおり、画像カードには media ID または media key への参照が含まれていません。その結果、メディアライブラリを通じてこれらのアセットを取得することはできません。これは [Account Media](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/account-media#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 ページ](https://developer.x.com/content/developer-twitter/en/docs/ads/general/overview/enums) の "Creative Types" を参照) を持つ画像がメディアライブラリに追加されると、自動的に Account Media アセットとして追加されます。クリエイティブタイプ (例: INTERSTITIAL) は画像の寸法によって決まります。
### ツイート
#### はじめに
X Ads API は、公開済み、予約済み、下書きの 3 種類のツイートをサポートしています。
#### ノルキャストされたツイート
ツイートはノルキャスト (別名「Promoted-only」) かオーガニックのいずれかになります。ノルキャストされたツイートは、公開されてもユーザーの公開タイムラインには表示されませんが、公開状態であることに変わりはありません。一方、オーガニックツイートはユーザーのフォロワーに配信され、ユーザーの公開タイムラインにも表示されます。 **ツイートの作成** 3 つのツイート作成エンドポイントそれぞれは、ツイートをノルキャストにするかオーガニックにするかを選択できるブール値の `nullcast` パラメーターをサポートしています。ノルキャストされたツイートは、そのユーザー本人か、ユーザーの代理としてツイートを作成する権限を持つユーザーであれば作成できます。オーガニックツイートを作成できるのは、[フルプロモーション可能ユーザー](https://developer.x.com/content/developer-twitter/en/docs/tutorials/ads-api-hierarchy-terminology#promotable-users) のみです。 **ツイートの更新** 予約済みツイートおよび下書きツイートについては、`nullcast` プロパティを更新できます。予約済みツイートは、そのツイートの `scheduled_at` 時刻まで編集可能です。下書きツイートは無期限に編集できます。ただし、一度公開されると、そのツイートをノルキャストからオーガニックへ、またはその逆に変更することはできません。
#### プロモーションするツイート
プロモーションできるのは、公開済みツイートと予約ツイートのみです。これらはノルキャストでもオーガニックでもかまいません。広告主は、自分のツイートだけでなく、許可を得ている限り他のユーザーのツイートもプロモーションできます。 (詳細は「[他のユーザーのツイートをプロモーションする](https://developer.x.com/content/developer-twitter/en/docs/tutorials/promoting-another-users-content)」を参照してください。) 1 つのキャンペーンで複数のツイートをプロモーションすることができます。同様に、1 つのツイートを 1 つ以上のキャンペーンでプロモーションすることもできます。 公開済みツイートをプロモーションするには、[POST accounts/:account\_id/promoted\_tweets エンドポイント](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/promoted-tweets#post-accounts-account-id-promoted-tweets)を使用します。これにより、公開済みツイートがラインアイテムに関連付けられます。予約ツイートをプロモーションするには、[POST accounts/:account\_id/scheduled\_promoted\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/scheduled-promoted-tweets#post-accounts-account-id-scheduled-promoted-tweets) エンドポイントを使用します。
#### ツイートID
公開済み、予約済み、および下書きのツイートIDは[数値](https://developer.x.com/content/developer-twitter/en/docs/basics/twitter-ids)であり、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](https://business.x.com/en/advertising/carousels.html)」ページをご覧ください。 カルーセルは、他のカードと同様にツイート内で使用でき、それらのツイートをプロモーション配信できます。ワークフローは、すでに慣れ親しんでいるものと同じです。 1. メディアをアップロードする 2. カードを作成する 3. ツイートを作成する 4. ツイートをプロモーション配信する 唯一の違いはカードの作成方法です。他のカード作成リクエストがクエリパラメータを受け付けるのに対し、カルーセルカード作成リクエストは JSON 形式の POST ボディのみを受け付けます。
#### エンドポイント
Ads API では、カルーセルの作成および取得が可能です。 任意の種類のカルーセルを作成するには、[POST accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#post-accounts-account-id-cards) エンドポイントを使用します。カルーセルを取得するには、[GET accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/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](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/media-library#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 つのアプリ識別子が必要です。オプションとしてディープリンクを指定できます。これらのフィールドの説明については、[リファレンスドキュメント](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#app-destination)を参照してください。 以上を踏まえたアプリカルーセルの 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 ガイド](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/media-library)を参照してください。 メディアアセットが Media Library に追加されたら、[GET accounts/:account\_id/media\_library](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/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](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#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](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/tweets#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](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/tweet-previews#get-accounts-account-id-tweet-previews) エンドポイントを使用して、ツイートを確認してください。
### クリエイティブ メタデータのタグ付け
#### はじめに
このガイドは、クリエイティブパートナー、代理店、およびクリエイティブ開発者を対象としており、Xキャンペーン内で使用されるアセットにタグ付けすることで、個々のアセットの価値とパフォーマンスをより正確に把握できるようにするものです。 **注意:** メディアアセットには、そのメディアアセットを作成したパートナーまたは開発者のみがタグを付与する必要があります。メディアアセットの利用者がそのメディアアセットを作成していない場合は、メタデータタグ付けを実装しないでください。 Creative Metadata Tagging は、クリエイティブパートナーによって作成された画像や動画について、アセットが X にアップロードされる場所やアップロードする主体を問わず、帰属情報を付与できるようにします。クリエイティブアセットとクリエイティブパートナーの関連付けを行うために、[XMP](https://exiftool.org/TagNames/XMP.html) 標準が使用されます。
#### クリエイティブアセットへのタグ付け
次の表は、各画像関連リソースのレスポンスで現在利用可能な識別子タイプと、それに対応する属性名を示しています。クリエイティブアセットにタグを付けるには、タグ付けツールが必要です。[ExifTool](https://exiftool.org/) (プラットフォームに依存しない Perl ライブラリと、メタ情報の読み取り・書き込み・編集用の[コマンドラインアプリケーション](https://exiftool.org/exiftool_pod.html)のセット) を推奨します。サポートされているすべての[ファイルタイプ](https://exiftool.org/#supported)を参照してください。 [ExifTool をインストールする手順](https://exiftool.org/install.html)に従ってください。[Homebrew](https://formulae.brew.sh/) が提供しているソフトウェアパッケージを利用すると、macOS と Linux 向けの [exiftool インストールコマンド](https://formulae.brew.sh/formula/exiftool)が用意されており、インストールをさらに簡略化できます。コマンドラインで `exiftool -ver` を実行し、ツールのバージョン番号が返されることを確認して、正しくインストールされているか確かめてください。ExifTool のコマンドパラメータの詳細は [ExifTool documentation](https://exiftool.org/) を参照してください。 クリエイティブパートナーは、新規または既存のクリエイティブアセットに対して、自身の X app\_id を contributor XMP タグおよび date タグにメタデータとして付与できます。クリエイティブアセットは、[メディアのアップロード](https://developer.x.com/en/docs/twitter-api/v1/media/upload-media/overview)時と同じサイズ制限に従います。  **Note:** X における contributor XMP タグの利用により、メタデータには X 上のキャンペーン専用の値のみが記録されるようになります。 `exiftool -contributor="" -creative_file.jpg` `exiftool -date="" -creative_file.jpg` app\_id は、[開発者コンソール](https://developer.x.com/en/portal/dashboard) の「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 ` 例: `exiftool -xmp:all -G1 eiffel_tower.jpg` ``` [XMP]        XMP Toolkit            : Image::ExifTool 12.30 ``` ``` [XMP]        Contributor            : 858382169 ``` ``` [XMP]        Date                   : 2022:03:13 ```
#### 質問はありますか？
タグ付けおよびアトリビューションが正しく行われているか確認したい場合は、タグ付け済みのアセットのサンプルを [adsapi-program@x.com](mailto:adsapi-program@x.com) 宛てに送付し、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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/x-ads-api/introduction) を参照してください。 Type: string Example: `8x7v00oow` | | sort\_by *optional* | サポートされている属性で昇順または降順にソートします。詳細は [Sorting](https://developer.x.com/x-ads-api/fundamentals/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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`](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet)、[`POST statuses/update`](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update)、[`POST accounts/:account_id/scheduled_tweets`](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets)、または [`POST accounts/:account_id/draft_tweets`](https://developer.x.com/en/docs/ads/creatives/api-reference/draft-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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/x-ads-api/introduction) を参照してください。 Type: string Example: `8x7v00oow` | | include\_legacy\_cards *optional* | レスポンスに従来の Website カードおよび App カードを含めます。従来のカードとは、リソース URL が次の形式になっているカードを指します: accounts/:account\_id/cards/:card\_type。追加のコンテキストについては [この開発者フォーラムの投稿](https://devcommunity.x.com/t/new-cards-endpoints-and-carousel-ads/145782/6) を参照してください。 Type: boolean Default: `false` Possible values: `true`, `false` | | q *optional* | `name` によってカードを絞り込むための任意のクエリです。すべてを取得する場合はこのパラメーターを省略します。最大長: 80 文字。 **Note**: 大文字小文字を区別しない前方一致でマッチングを行います。 Type: string Example: `dtc` | | sort\_by *optional* | サポートされている属性で昇順または降順にソートします。詳細は [Sorting](https://developer.x.com/x-ads-api/fundamentals/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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 ガイド](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://en.wikipedia.org/wiki/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts) を除くすべての Advertiser API リクエストで通常は必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t` | | count *optional* | 1 回のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: `100` Min, Max: `1`, `200` | | cursor *optional* | 次のページの結果を取得するためのカーソルを指定します。詳細は [Pagination](https://developer.x.com/x-ads-api/introduction) を参照してください。 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts) を除くすべての Advertiser API リクエストで、一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: `18ce54d4x5t` | | as\_user\_id *必須* | ツイートを代理投稿する広告主のユーザー ID です。広告主は、[ads.x.com](https://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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet)、[POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update)、または [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/x-ads-api/introduction) を参照してください。 Type: string Example: `8x7v00oow` | | q *optional* | `name` で card を絞り込むための任意のクエリです。すべてを取得する場合はこのパラメータを省略します。最大長：80 文字。 **Note**: 大文字・小文字を区別しない前方一致で検索します。 Type: string Example: `night` | | sort\_by *optional* | サポートされている属性で、昇順または降順にソートします。詳細は [Sorting](https://developer.x.com/x-ads-api/fundamentals/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/rest/public/uploading-media) を参照してください。
#### リソース URL
`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation`
#### Parameters
| Name | Description | | :---------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | account\_id *required* | 対象となるアカウントの識別子。リソースパス内に含まれ、[GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#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](https://developer.x.com/rest/public/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts) を除くすべての Advertiser API リクエストで、一般に必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t` | | count *optional* | 1 回のリクエストで取得を試みるレコード数を指定します。 Type: int Default: `20` Min, Max: `1`, `50` | | cursor *optional* | 次のページの結果を取得するためのカーソルを指定します。詳細は [Pagination](https://developer.x.com/x-ads-api/introduction) を参照してください。 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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 ガイド](https://developer.x.com/en/docs/ads/creatives/guides/media-library)をご覧ください。 **注**: `AMPLIFY_VIDEO` メディアカテゴリの動画を Media Library に追加すると、その動画は自動的に `PREROLL` の [account\_media](https://developer.x.com/en/docs/ads/creatives/api-reference/account-media#get-accounts-account-id-account-media) アセットとして利用可能になります。 #### リソースURL `https://ads-api.x.com/12/accounts/:account_id/media_library` #### パラメーター | Name | Description | | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | account\_id *required* | 対象アカウントの識別子。リソースのパス内に含まれ、[GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#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](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts) を除くすべての Advertiser API リクエストで通常、必須パラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t` | | media\_key *必須* | リクエストで操作するメディアライブラリオブジェクトを指定します。 Type: string Example: `16_844800354743074820` | | description *任意* | ツイートされた際に動画の下に表示される説明文です。最大文字数: 200 文字。 この説明文は既定ではツイート内に表示されません。動画の `description` を表示するには、[POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#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](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/x-ads-api/introduction) を参照してください。 Type: string Example: `8x7v00oow` | | q *optional* | `name` でカードを絞り込むための任意のクエリです。すべて取得するにはこのパラメーターを省略します。最大長: 80 文字。 **Note**: 大文字・小文字を区別しない前方一致検索を行います。 Type: string Example: `night` | | sort\_by *optional* | サポートされている属性を、昇順または降順でソートします。詳細は [Sorting](https://developer.x.com/x-ads-api/fundamentals/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/x-ads-api/introduction) を参照してください。 Type: string Example: `8x7v00oow` | | preroll\_call\_to\_action\_ids *optional* | カンマ区切りの識別子リストを指定して、レスポンスを対象の preroll CTA のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: `8f0` | | sort\_by *optional* | サポートされている属性を昇順または降順でソートします。詳細は [Sorting](https://developer.x.com/x-ads-api/fundamentals/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts) を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: `18ce54d4x5t` | | count *任意* | 個々のリクエストごとに取得するレコード数を指定します。 型: int 既定値: `100` 最小値/最大値: `1` / `200` | | cursor *任意* | 次のページの結果を取得するためのカーソルを指定します。詳細は [Pagination](https://developer.x.com/x-ads-api/introduction) を参照してください。 型: 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts) を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t` | | scheduled\_at *required* | ツイートが公開される時刻を [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 形式で指定します。 **Note**: ツイートをスケジュールできるのは、最大で 1 年先までです。 **Note**: ツイートは分単位の粒度でのみスケジュールしてください。秒は無視されます。 Type: string Example: `2017-12-31T23:59:00Z` | | as\_user\_id *required* | ツイートを代理投稿する広告主のユーザー ID です。広告主は、[ads.x.com](https://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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library) に存在している必要があります。 **Note**: 値を指定せずにパラメータのみを指定すると、未設定 (削除) されます。 Type: string Example: `13_1153584529292270722` | | nullcast *optional* | ツイートを nullcast (「Promoted-only」) として作成するかどうかを指定します。 Type: boolean Possible values: `true`, `false` | | scheduled\_at *optional* | ツイートを公開 (または配信開始) する時刻を、[ISO 8601](https://en.wikipedia.org/wiki/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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#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": "