概要
- POST accounts/:account_id/cards Tweets:
- POST accounts/:account_id/tweets - Tweets にカードを追加するには、card_uri パラメータを使用します。 Scheduled Tweets:
- POST accounts/:account_id/scheduled_tweets
カード
画像
- 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
動画
- ビデオウェブサイト: 16:9 と 1:1
- ビデオ App ダウンロード: 16:9 と 1:1
- 投票: 16:9
- ビデオ会話: 16:9
- ビデオダイレクトメッセージ: 16:9
プロモーテッド動画
media_id を用いて POST accounts/:account_id/videos endpoint で動画を広告アカウントに関連付けます。動画の id（media_key と呼ばれることもあります）は、以降のリクエストで使用します。これは、先頭が整数、続いてアンダースコア、末尾に長い値が続く文字列です。例: 13_875943225764098048。
ツイート内のプロモート動画
id とともに POST accounts/:account_id/tweet endpoint を使用します。この段階で、動画のタイトル、説明、CTA（コールトゥアクション）も指定できます。これらの値はユーザーに表示されます。
カードのPromoted Video
- POST accounts/:account_id/cards/video_website
- POST accounts/:account_id/cards/video_app_download
- POST accounts/:account_id/cards/video_conversation
idと、必要に応じて画像のmedia_id（ポスター画像用）を使用します。
最後に、POST accounts/:account_id/tweet endpointを使用してTweetを作成します。カードはcard_uriパラメータを使用してTweetsに添付されます。
一般情報
- （2015-10-22 時点）プロモーション用コンテンツで使用する動画をアップロードする場合は、POST media/upload (chunked) endpoint へのすべての
INITコマンドのリクエストで、media_categoryパラメータにamplify_videoを設定する必要があります。このパラメータを使用すると、動画が非同期で前処理され、プロモーション用コンテンツで使用できるように準備されます。動画アップロード後の非同期処理の完了確認にはSTATUSコマンドを使用できます。 - 現在許可されているプロモーション動画の最大長は 10 分、ファイルサイズは 500MB 以下です。
- アップロードする動画は mp4 または mov のいずれかにしてください。
- アップロードされた動画は通常迅速に処理されますが、処理時間は動画の長さやファイルサイズによって変動します。
- アップロードするポスター画像は png または jpg 形式である必要があります。アスペクト比やサイズの要件はありませんが、ポスター画像は動画プレーヤーに合わせて調整されます。
ガイド
予約済みTweets
はじめに
- 新規にスケジュールした Tweet の作成・変更・閲覧
- スケジュール済みの Tweet をラインアイテムに関連付け
- 既存のスケジュール済み Tweet の query と管理
- スケジュール済みの Tweet が公開された後に、公開済み Tweet の
idを取得
API endpoint
予約済みTweetの管理
- GET accounts/:account_id/scheduled_tweets（すべての予約済みTweet一覧を取得）
- GET accounts/:account_id/scheduled_tweets/:scheduled_tweet_id（
idを指定して特定の予約済みTweetを取得） - POST accounts/:account_id/scheduled_tweets（新規の予約済みTweetを作成）
- PUT accounts/:account_id/scheduled_tweets/:scheduled_tweet_id（既存の予約済みTweetを更新）
- DELETE accounts/:account_id/scheduled_tweets/:scheduled_tweet_id（
idを指定して予約済みTweetを削除） - GET accounts/:account_id/scheduled_tweets/preview/:scheduled_tweet_id（既存の予約済みTweetをプレビュー）
予約済みプロモツイート
- GET accounts/:account_id/scheduled_promoted_tweets（すべての予約済みプロモツイートの一覧を取得）
- GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id（
idを指定して予約済みプロモツイートを取得） - POST accounts/:account_id/scheduled_promoted_tweets（新しい予約済みプロモツイートを作成）
- DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id（
idを指定して既存の予約済みプロモツイートを削除）
予約済みTweetビュー
予約済みTweetの作成:
- 認証ユーザーが、指定の@handleに対してオーガニックTweetを作成できる権限を持つことを確認してください。Promoted-Only Tweetの作成権限には、認証ユーザーがTweet composer permissionsを持つアカウントユーザーである必要があります。
- scheduled_at時刻の前後15分のウィンドウ内で作成予定のTweetが30件を超えないことを確認してください。SCHEDULED_TWEET_LIMIT_EXCEEDEDエラーメッセージは、同一の将来の15分枠内に予約済みTweetが多すぎることを示します。広告主は既存の予約済みTweetを削除するか、scheduled_at時刻を前倒しまたは後ろ倒しにしてください。
スケジュール済みの Tweet が「公開」されるタイミング:
- これらの検証ルールは scheduled_at の時刻に実行され、API での通常の Tweet 作成時に適用されるものと同一です。たとえば、スケジュール済みの Tweet に画像と GIF の両方が含まれている場合は公開されず、scheduled_status は FAILED に設定されます
ワークフロー
scheduled_at（実行時刻）と、Tweet にメディアエンティティが含まれない場合の Tweet の text です。加えて、この endpoint では、as_user_id パラメータを使って別の @handle の代理で Scheduled Tweet を作成できるほか、カード（card_uri）やメディア（media_ids）を追加するためのオプションも提供しています。注意: Tweet には同一の type のエンティティのみを含められます。つまり、Video・Gif・Image のいずれかです。nullcast パラメータは、その Tweet を「Promoted-Only」Tweet にするかどうかを制御します。新規に作成された Scheduled Tweet は、デフォルトで「Promoted-Only」（nullcast=true）です。nullcast=false の場合は、オーガニックな Scheduled Tweet が作成されます。
Scheduled Tweet が正常に作成されると、レスポンスには Scheduled Tweet 自体の一意の識別子を示す id フィールドが含まれます。これに加えて、tweet_id というフィールドも返されます。このフィールドは当初は null ですが、Tweet が公開されると、「ライブ」Tweet の ID が設定されます。
tweet_id フィールドには「ライブ」Tweet の ID が設定されます。
Scheduled Tweet を表示
GET accounts/:account_id/tweet_previews endpoint を、前の手順で取得した Scheduled Tweet の id と組み合わせて使用することで、Tweet のプレビューを生成できます。API レスポンスには、Scheduled Tweet のプレビューを表示するためにそのまま使用できる iframe の URL が含まれます。関連する CSS と画像は X から直接配信されます。
nullcast=true）の Tweet を作成することもでき、いずれもラインアイテムに関連付け可能です。これを実現するために、POST accounts/:account_id/scheduled_promoted_tweets endpoint も提供しています。この endpoint では、1 回の API コールで 1 つの Promoted Scheduled Tweet のみをラインアイテムに関連付けられます。同一のラインアイテムに複数の Scheduled Tweets を関連付けるには、複数回の API コールが必要です。
既存の Scheduled Promoted Tweet を変更することはできませんのでご注意ください。
SCHEDULED状態であること、および当該Scheduled Tweetが指定の目的に対して有効であることのみを検証し、それ以外の検証は行いません。ラインアイテムおよびScheduled Tweetに適用される残りの検証ルールは、Tweetが「ライブ」になったタイミングで実行されます。
キャンペーン配信に問題が発生しないよう、Scheduled Tweetはキャンペーン／ラインアイテムのフライト期間より前の時刻にscheduled_atされていることを推奨します。
たとえば、Scheduled Tweetがキャンペーン開始日より後にライブになるよう設定されている場合（かつ単一のラインアイテムに単一のTweetのみが関連付けられている場合）、キャンペーンはACTIVEになりますが、Scheduled Tweetがまだライブでないため、配信可能なクリエイティブは存在しません。
Scheduled Tweetの管理
残りの一連のendpointにより、API利用者は、すべてのScheduled TweetおよびScheduled Promoted Tweetを管理できます。これらのAPIは、任意の状態でフィルタしてすべてのScheduled Tweetの一覧を返す、または指定したidでScheduled Tweetを参照するために使用できます。
スケジュール済みTweetが公開されるとどうなりますか？
scheduled_at の時刻になると、次の更新が行われます。
- 「ライブ」のTweetが作成されますが、最大で1秒程度の遅延が発生する場合があります
tweet_idが次のエンティティに追加されます:- スケジュール済みTweet
- プロモーション対象のスケジュール済みTweet
- 新しいプロモーション対象のTweetエンティティが作成されます
ベストプラクティス
- Scheduled Tweet を作成する際は、その Tweet が有効な内容であることを確認してください（例：Tweet には画像・動画・GIFのいずれか1つのみを含められ、複数の組み合わせは不可）
- キャンペーンのフライト期間（つまり
start_timeとend_time）が、Scheduled Tweet のscheduled_at時刻と整合していることを確認してください - Scheduled Tweets を1年（365日）より先の日時に設定しないでください
- Scheduled Tweets では現在、Tweet のプレビュー機能はサポートされていません（作成前に Scheduled Tweet をプレビューする機能）
メディア ライブラリ
はじめに
API エンドポイント
- POST media/upload または POST media/upload (chunked)（メディアをアップロード）
- POST accounts/:account_id/media_library（メディアライブラリにメディアを追加）
ライブラリへの追加
リクエストパラメータ
属性
使い方
カードの識別方法
はじめに
| card_uri | preview_url |
|---|---|
| card://1043282691834048513 | https://cards.x.com/cards/18ce54d4x5t/68w3s |
card_uri で Tweet を特定する
card の URI 値を使用して作成された Tweet では、card への参照は card_uri レスポンス属性に含まれます。以下の例のレスポンスは GET accounts/:account_id/tweets endpoint を使用しています。preview_url を用いた Tweet の識別
Tweet の本文にプレビュー URL を含めて作成された場合、URL は entities[“urls”][i][“expanded_url”] にあります（text フィールドには短縮された t.co の URL が含まれます）。ここで i は配列のインデックスです（1 つの Tweet に複数の URL を含められます）。 予約投稿および下書きの Tweet オブジェクトでは、プレビュー URL は常に text フィールドに含まれます。カードの取得
メディアの特定
はじめに
| メディア ID | メディアキー |
|---|---|
| 1029825579531807971 | 13_1029825579531807971 |
画像
| Resource | Identifier | Attribute(s) |
|---|---|---|
| Image cards | なし | |
| Tweet | 両方 | entities["media"]["id_str"] entities["media"]["media_key"] |
| Scheduled Tweet | 両方 | media_ids と media_keys |
| Draft Tweet | 両方 | media_ids と media_keys |
| Account Media | なし | |
| Media Library | 両方 | media_id と media_key |
| Resource | Attribute(s) | Format |
|---|---|---|
| Image cards | image | .jpg |
| Tweet* | entities["media"][0]["media_url"] または extended_entities["media"][i]["media_url"] | .jpg |
| Scheduled Tweet | なし | |
| Draft Tweet | なし | |
| Account Media | media_url | .jpg |
| Media Library | media_url | .jpg |
- この URL の位置は、Tweet に単一画像が含まれるか複数画像が含まれるかによって異なります。
動画
| 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 and media_keys |
| Draft Tweet | 両方 | media_ids and media_keys |
| Account Media | Media key | video_id |
| Media Library | 両方 | media_id and media_key |
video_content_id レスポンス属性が含まれますが、返却される値の型に一貫性がありません。メディアIDの場合もあれば、メディアキーの場合もあります。
動画のURLへのアクセス方法は以下のとおりです。
| Resource | Attribute(s) | Format |
|---|---|---|
| Video cards | video_url and 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_url と video_hls_url のレスポンス属性が含まれ、URLはそれぞれ .vmap と .m3u8 です。
メディアライブラリ
| Resource | In the Media Library |
|---|---|
| 画像カード | No |
| ビデオカード | Yes* |
| Tweets（任意のメディア）** | Yes |
| 予約済み Tweets | Yes |
| 下書き Tweets | Yes |
| Account media 画像 | No |
Account media 動画（PREROLL） | Yes |
video_content_idが media key であるカードの場合。値が media ID の場合でもアセットはメディアライブラリに存在しますが、取得するにはその前に数値のプレフィックスとアンダースコアを付与する必要があります。
** Tweets は media ID のみを返します。アセットがメディアライブラリに存在することは保証されていますが、取得するにはその前に数値のプレフィックスとアンダースコアを付与する必要があります。
- AMPLIFY_VIDEO アセットがメディアライブラリに追加されると、クリエイティブタイプ PREROLL の Account Media アセットとして自動的に追加されます。
- 特定の寸法（enumerations page の「Creative Types」を参照）を満たす画像がメディアライブラリに追加されると、自動的に Account Media アセットとして追加されます。クリエイティブタイプ（例：INTERSTITIAL）は画像の寸法によって決まります。
Tweets
はじめに
Nullcasted Tweets
Tweetのプロモーション
TweetのID
カルーセル
はじめに
- メディアをアップロード
- カードを作成
- Tweet を作成
- Tweet をプロモーション
エンドポイント
JSON POST ボディ
SWIPEABLE_MEDIAコンポーネントを 1 つ（メディアキーの配列を受け取ります）- 次のいずれかを 1 つ:
- ウェブサイト情報を指定する
DETAILSコンポーネント - App 情報を指定する
BUTTONコンポーネント
SWIPEABLE_MEDIA コンポーネントには media_keys 配列を含める必要があり、2～6 個の画像または動画を指定できます。渡したメディアキーの順序が、レンダリングの順序を決定します。
| Website | App | |
|---|---|---|
| コンポーネントの種類を指定 | "type": "DETAILS" | "type": "BUTTON" |
| タイトル/ラベル | "title": "X" | "label": { "type": "ENUM", "value": "INSTALL" } |
| 遷移先 | "destination": { "type": "WEBSITE", "url": "https://www.x.com" } | "destination": { "type": "APP", ... } |
BUTTON コンポーネント内の App 宛先オブジェクトには、国コードと少なくとも 1 つのアプリ識別子が必須です。オプションでディープリンクも指定できます。これらの fields の説明は、リファレンス ドキュメントを参照してください。
これらを踏まえると、アプリ カルーセルの JSON POST ボディ例は以下のとおりです。
例
media_type リクエストパラメータを使用して、特定のメディアタイプに結果を絞り込みます。
card_uri が含まれており、Tweet の作成時に使用します。
Tweet
POST accounts/:account_id/tweet endpoint を使用して Tweet を作成します。前のリクエストで取得した card_uri を使用してください。（可読性のため、レスポンスは一部省略しています。）
クリエイティブのmetadataタグ付け
はじめに
クリエイティブアセットへのタグ付け
exiftool -contributor="<YOUR APP ID>" -creative_file.jpg
exiftool -date="<date>" -creative_file.jpg
app_id は Developer Portal の Projects & Apps で確認できます。例: 16489123
次の例では、画像に対して app_id を contributor タグに、date を date タグに追加しています:
exiftool -xmp:all -G1 <filename>
例:
exiftool -xmp:all -G1 eiffel_tower.jpg
ご質問がありますか？
API リファレンス
アカウントメディア
GET accounts/:account_id/account_media
現在のアカウントに紐づくアカウントメディアの一部またはすべての詳細を取得します。リソース URL
https://ads-api.x.com/12/accounts/:account_id/account_media
パラメータ
| Name | Description |
|---|---|
| account_id 必須 | 利用するアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに紐づいている必要があります。 Type: string Example: 18ce54d4x5t |
| account_media_ids 任意 | 識別子をカンマ区切りで指定して、レスポンスを目的のアカウントメディアのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 3wpx |
| count 任意 | 個別のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000 |
| creative_types 任意 | 指定したクリエイティブタイプに一致するアカウントメディアのみにレスポンスを絞り込みます。列挙値をカンマ区切りで複数指定できます。 Type: enum Possible values: BANNER, BANNER_TABLET, INTERSTITIAL, INTERSTITIAL_LANDSCAPE, INTERSTITIAL_LANDSCAPE_TABLET, INTERSTITIAL_TABLET, MEDIUM_RECTANGLE, PREROLL, VAST_PREROLL |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow |
| sort_by 任意 | サポートされる属性で昇順または降順に並べ替えます。詳細は Sorting を参照してください。 Type: string Example: created_at-asc |
| with_deleted 任意 | 削除済みの結果を含めます。 Type: boolean Default: false Possible values: true, false |
| with_total_count 任意 | レスポンス属性 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
応答例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id
パラメーター
| Name | Description |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須のパラメーターです。指定したアカウントは認証済みユーザーに紐づいている必要があります。 Type: string 例: 18ce54d4x5t |
| account_media_id 必須 | リクエストで操作対象となるアカウントメディアの参照。 Type: string 例: 2pnfd |
| with_deleted 任意 | 削除済みの結果をレスポンスに含めます。 Type: boolean 既定値: false 取りうる値: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd
例
リソースURL
https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id
パラメータ
| Name | Description |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| account_media_id 必須 | リクエストで操作対象となるアカウントメディアを参照します。 Type: string Example: 2pnfd |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd
例のレスポンス
カード
card_uri パラメータを使用し、POST accounts/:account_id/tweet、POST statuses/update、POST accounts/:account_id/scheduled_tweets、または POST accounts/:account_id/draft_tweets のいずれかの endpoint を使用します。
現在のアカウントに関連付けられているカードの詳細を、必要に応じて一部またはすべて取得します。
注記: 返されるのは、POST accounts/:account_id/cards endpoint を使用して作成されたカードのみです。他の endpoint で作成されたカードは返されません。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards
パラメータ
| Name | Description |
|---|---|
| account_id required | 使用するアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string 例: 18ce54d4x5t |
| card_types optional | 列挙値をカンマ区切りで指定して、応答を目的のカードタイプのみに絞り込みます。 Type: enum 取りうる値: 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 | 識別子をカンマ区切りで指定して、応答を目的のカードのみに絞り込みます。カード ID は最大 200 個まで指定できます。 Type: string 例: 1044294149527166979,1044301099031658496 |
| card_uris optional | 識別子をカンマ区切りで指定して、応答を目的のカードのみに絞り込みます。カード URI の値は最大 200 個まで指定できます。 Type: string 例: card://1044294149527166979,card://1044301099031658496 |
| count optional | 個々のリクエストあたりで取得を試みるレコード数を指定します。 Type: int 既定値: 100 最小/最大: 1/200 |
| cursor optional | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string 例: 8x7v00oow |
| include_legacy_cards optional | 応答にレガシーの website および app カードを含めます。レガシーカードとは、リソース URL が accounts/:account_id/cards/:card_type の形式であるものを指します。詳しくは この開発者フォーラムの投稿 を参照してください。 Type: boolean 既定値: false 取りうる値: true, false |
| q optional | name でカードを絞り込むための任意の query。すべて取得する場合はこのパラメータを省略します。最大長: 80 文字。 注: 大文字小文字を区別しない前方一致で照合します。 Type: string 例: dtc |
| sort_by optional | サポートされる属性で昇順または降順に並べ替えます。詳細は Sorting を参照してください。 Type: string 例: created_at-asc |
| with_deleted optional | 削除済みの結果を含めます。 Type: boolean 既定値: false 取りうる値: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1
例のレスポンス
リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards/:card_id
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | 利用するアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_id 必須 | カードのid。 Type: string Example: 1044294149527166979 |
| with_deleted 任意 | 削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264
返答例
POST accounts/:account_id/cards
指定したアカウントに関連付けられた新しいカードを作成します。 カード作成リクエストでは、JSON の POST 本文のみが受け付けられます。Content-Type は application/json に設定する必要があります。
詳しい使用例は、Carousels Guide を参照してください。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards
パラメーター
name と components の配列を必ず含めてください。components はオブジェクトとして表され、カードの広告主向け属性を記述します。
次の例は、ペイロードの一般的な構造を示しています（ただし、実際には動作しない情報が含まれています）。
| Name | Description |
|---|---|
| account_id required | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| name required | カード名。最大長: 80 文字。 Type: string Example: component based card |
| components sometimes required | カード作成に使用するコンポーネントを記述します。詳細は以下を参照。slides と同時には指定できません。注: コンポーネントの順序は重要です。 Type: array of objects |
| slides sometimes required | Multi-Destination Carousel を作成するためにこの配列の配列を使用します。各カードをコンポーネントのグループとして記述します。各スライドはカードの完全な表現である必要があります。components と同時には指定できません。注: 各スライドの順序は重要です。 Type: array of array |
コンポーネント
type フィールドを含める必要があります。X Ads API は、以下のコンポーネントタイプをサポートしており、メディア系コンポーネントと説明系コンポーネントに分類されます。
- メディア:
MEDIA: 単一の動画または画像SWIPEABLE_MEDIA: 2〜6 本/枚の動画または画像- 説明:
DETAILSBUTTON
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 キーを省略）。（省略記号は、追加の情報を指定する必要がある箇所を示します。）
DETAILS または BUTTON コンポーネントのいずれかを組み合わせて作成する必要があります。説明ベースのコンポーネントはメディアの下にレンダリングされ、URL またはモバイルアプリのいずれかを遷移先として持ちます。
Label
Label はボタンに表示されるテキストを定義し、そのため BUTTON コンポーネントにのみ適用されます。Label オブジェクトには必須キーが 2 つあります: type と value。type は ENUM に設定する必要があり、value は BOOK、CONNECT、INSTALL、OPEN、ORDER、PLAY、SHOP のいずれかです。
前の例を踏まえて、以下は BUTTON コンポーネント内の label オブジェクトの例です。
DETAILS または BUTTON コンポーネント内で常に必須です。宛先の種類は WEBSITE と APP の2種類です。
注: Website 宛先は DETAILS コンポーネントでのみ使用でき、App 宛先は BUTTON コンポーネントでのみ使用できます。
Website 宛先
| Name | Description |
|---|---|
| type required | 宛先の種類。スキーマを決定します。 Type: enum Possible values: WEBSITE |
| url required | ユーザーのリダイレクト先となるウェブサイトの URL。 Type: string Example: https://devcommunity.x.com/c/advertiser-api |
| Name | Description |
|---|---|
| type required | 宛先の種類。スキーマを決定します。 Type: enum Possible values: APP |
| country_code required | アプリが販売されている国の ISO 3166-1 alpha-2 の2文字コード。 Type: string Example: US |
| googleplay_app_id sometimes required | Google Play のアプリケーションパッケージ名。 注: 次のいずれかを少なくとも1つ指定する必要があります: ios_app_store_identifier または googleplay_app_id。 Type: string Example: com.twitter.android |
| ios_app_store_identifier sometimes required | iOS App Store の識別子。 注: 次のいずれかを少なくとも1つ指定する必要があります: ios_app_store_identifier または googleplay_app_id。 Type: string Example: 333903271 |
| googleplay_deep_link optional | プロモーション対象の Android アプリへのディープリンク。 注: googleplay_app_id が指定されている場合にのみ使用できます。 Type: string |
| ios_deep_link optional | プロモーション対象の iOS アプリへのディープリンク。 注: ios_app_store_identifier が指定されている場合にのみ使用できます。 Type: string |
リクエスト例
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards
例: レスポンス
Content-Type は application/json に設定する必要があります。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/1321554298900107264
パラメータ
| Name | Description |
|---|---|
| account_id required | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| name optional | カード名。最大 80 文字。 Type: string Example: component based card |
| components optional | カードの更新に使用するコンポーネントを記述します。詳細は下記を参照。slides と同時には指定できません。注: コンポーネントの順序は重要です。 Type: array of objects |
| slides optional | Multi-Destination Carousel を更新するために、この二次元配列を使用します。各カードをコンポーネントのグループとして記述します。各スライドはカードを完全に表す必要があります。components と同時には指定できません。注: 各スライドの順序は重要です。 Type: array of array |
リクエスト例
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264
レスポンス例
リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards/:card_id
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象（レバレッジド）アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_id 必須 | 削除するカードの id。 Type: string Example: 1044294149527166979 |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264
応答例
Cards Fetch
card_uri を指定して、複数のカードを取得します。
リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards/all
パラメーター
| Name | Description |
|---|---|
| account_id required | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_uris required | 識別子のカンマ区切りリストを指定して、応答を目的のカードのみに絞り込みます。最大 200 個のカード 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
サンプルレスポンス
card_id を指定して取得します。
リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards/all/:card_id
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須となるパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string 例: 18ce54d4x5t |
| card_id 必須 | リクエストで操作対象となるカードを指す参照。 Type: string 例: 508pf |
| with_deleted 任意 | 削除済みの結果をレスポンスに含めます。 Type: boolean 既定値: false 取りうる値: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all/508pf
例のレスポンス
ツイートの下書き
GET accounts/:account_id/draft_tweets
現在のアカウントに関連付けられている Draft Tweets の一部またはすべての詳細を取得します。リソース URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets
パラメーター
| Name | Description |
|---|---|
| account_id required | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| count optional | リクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 100 Min, Max: 1, 200 |
| cursor optional | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: c-jh1g0ryb |
| user_id optional | Draft Tweets を取得する対象ユーザーを指定します。未設定の場合、アカウント上の FULL プロモータブルユーザーが既定になります。 Type: string Example: 756201191646691328 |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?count=1
応答例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| draft_tweet_id 必須 | リクエストで操作対象となる Draft Tweet への参照。 Type: string Example: 994788364334325760 |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994788364334325760
応答例
POST accounts/:account_id/draft_tweets
アカウントのフルプロモート対象ユーザー（デフォルト）またはas_user_id パラメータで指定したユーザーの下書きTweetを作成します。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets
パラメータ
| Name | Description |
|---|---|
| account_id required | レバレッジ対象のアカウントを識別する ID。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで基本的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| as_user_id required | 代理でTweetを投稿する広告主のユーザーID。広告主は ads.x.com から、あなたのハンドル（複数可）に自社の広告アカウントへのアクセス権を付与する必要があります。この許可により、広告主のハンドルではなく自身のハンドルの OAuth トークンで API を呼び出せます。 Type: string Example: 756201191646691328 |
| text sometimes required | ステータス更新の本文。media_keys が指定されていない場合は必須です。 Type: string Example: Just setting up my X. |
| card_uri optional | 利用可能な場合、任意の cards のレスポンスから取得した card_uri の値を使用して、Tweet にカードを関連付けます。 Type: string Example: card://960880280705392541 |
| media_keys optional | 識別子をカンマ区切りで指定して、Tweet にメディアを関連付けます。画像は最大 4 枚、アニメーション GIF は 1 つ、または動画は 1 つまで含められます。 Note: メディアアセットはアカウントの Media Library に存在している必要があります。 Type: string Example: 13_1153584529292270722 |
| nullcast optional | nullcast（「Promoted-only」）の Tweet を作成するかどうか。 Type: boolean Default: true Possible values: true, false |
| name optional | 下書きTweetの名前。最大 80 文字。 Type: string Example: Tweet with name |
リクエスト例
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.
応答例
リソースURL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id
パラメーター
| Name | Description |
|---|---|
| account_id 必須 | 対象のレバレッジドアカウントを示す識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで基本的に必須です。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| draft_tweet_id 必須 | リクエストで操作対象となる Draft Tweet への参照。 Type: string Example: 994747471329873920 |
| card_uri 任意 | 利用可能な場合、任意の cards レスポンスの card_uri 値を使用して Tweet にカードを関連付けます。 Note: 値を指定せずにパラメーターのみを渡すと未設定（削除）になります。 Type: string Example: card://970582057284129151 |
| media_keys 任意 | カンマ区切りの識別子リストを指定して Tweet にメディアを関連付けます。画像は最大 4 点、アニメーション GIF は 1 点、動画は 1 点まで含められます。 Note: メディアアセットはアカウントの Media Library に存在している必要があります。 Note: 値を指定せずにパラメーターのみを渡すと未設定（削除）になります。 Type: string Example: 13_1153584529292270722 |
| nullcast 任意 | nullcast（「Promoted-only」）Tweet を作成するかどうか。 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
応答例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| draft_tweet_id 必須 | リクエストで操作対象となる Draft Tweet への参照。 Type: string Example: 994787835663155200 |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200
レスポンス例
POST accounts/:account_id/draft_tweets/preview/:draft_tweet_id
モバイルデバイス上で Draft Tweet をプレビューします。 リクエストが成功すると、認証済みユーザーがログインしているすべてのデバイスに通知が送信されます。通知をタップするとタイムラインが開き、ユーザーは Draft Tweet を表示・操作できます。これにより、自動再生、音量、全画面表示、Video Website Card のドッキングなどの動作をテストできます。 注記: 端末上のプレビューは、通知を受け取ったユーザーにのみ表示されます。 注記: 通知は X の公式アプリにのみ送信されます。リソース URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_id
パラメーター
| Name | Description |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| draft_tweet_id 必須 | リクエストで操作する Draft Tweet への参照。 Type: string Example: 996132315829948416 |
リクエスト例
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416
応答例
画像会話カード
card_uri パラメータを使用し、POST accounts/:account_id/tweet、POST statuses/update、または POST accounts/:account_id/scheduled_tweets のいずれかの endpoint を利用してください。
GET accounts/:account_id/cards/image_conversation
現在のアカウントに関連付けられている Image Conversation Card の一部またはすべての詳細を取得します。リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation
パラメーター
| Name | Description |
|---|---|
| account_id required | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに紐づいている必要があります。 Type: string Example: 18ce54d4x5t |
| card_ids optional | 識別子のカンマ区切りリストを指定して、レスポンスを目的の Image Conversation Card のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 59woh |
| count optional | 各リクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor optional | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow |
| q optional | name でカードを絞り込むための任意の query。すべてを取得する場合はこのパラメーターを省略します。最大長: 80 文字。 Note: 大文字小文字を区別しないプレフィックス一致で検索します。 Type: string Example: night |
| sort_by optional | サポートされている属性で昇順または降順に並べ替えます。詳細は Sorting を参照してください。 Type: string Example: created_at-asc |
| with_deleted optional | 削除済みの結果を含めます。 Type: boolean Default: false Possible values: true, false |
| with_total_count optional | レスポンスに total_count 属性を含めます。 Note: このパラメーターと cursor は同時指定できません。 Note: total_count を含むリクエストはレートリミットが低く、現在は 15 分あたり 200 に設定されています。 Type: boolean Default: false Possible values: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?card_ids=59woh
応答例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id
パラメーター
| Name | Description |
|---|---|
| account_id required | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_id required | リクエストで操作する image conversation card への参照。 Type: string Example: 59woh |
| with_deleted optional | 削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh
例のレスポンス
POST accounts/:account_id/cards/image_conversation
指定したアカウントに関連付けられた新しい画像会話カードを作成します。 画像を当社のendpointにアップロードする際に役立つ情報については、Uploading Mediaを参照してください。リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation
パラメーター
| Name | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須です。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string 例: 18ce54d4x5t |
| first_cta 必須 | 1 つ目のオプションの Call-To-Action (CTA) 用ハッシュタグ。最大 20 文字（# はカウントしない）。 Type: string 例: #ShareNow |
| first_cta_tweet 必須 | 1 つ目の CTA がクリックされたときに使用する Tweet テキスト。 Type: string 例: I Heart @AdsAPI |
| media_key 必須 | このカードで使用する画像のメディアキー。 注: 画像はアカウントの Media Library に存在している必要があります。 注: 画像の最小幅は 800px、幅:高さのアスペクト比は 1.91:1 が必要です。 Type: string 例: 3_1151345051104991073 |
| name 必須 | カード名。 Type: string 例: image conversation card |
| thank_you_text 必須 | CTA クリック後に表示されるテキスト。最大 23 文字。 Type: string 例: Thank you |
| second_cta 条件付き必須 | 2 つ目のオプションの Call-To-Action (CTA) 用ハッシュタグ。最大 20 文字（# はカウントしない）。 Type: string 注: title が設定されていない場合に必須。 例: #ShareAgain |
| second_cta_tweet 条件付き必須 | 2 つ目の CTA がクリックされたときに使用する Tweet テキスト。 注: second_cta が設定されている場合に必須。 Type: string 例: I Heart @AdsAPI Again |
| title 条件付き必須 | 画像の下、CTA の上に表示されるカードのタイトル。最大 23 文字。 Type: string 注: second_cta が設定されていない場合に必須。 例: Start a conversation |
| third_cta 任意 | 3 つ目のオプションの Call-To-Action (CTA) 用ハッシュタグ。最大 20 文字（# はカウントしない）。 Type: string 例: #ShareMore |
| third_cta_tweet 条件付き必須 | 3 つ目の CTA がクリックされたときに使用する Tweet テキスト。 Type: string 注: third_cta が設定されている場合に必須。 例: I Heart @TwitterDev |
| fourth_cta 任意 | 4 つ目のオプションの Call-To-Action (CTA) 用ハッシュタグ。最大 20 文字（# はカウントしない）。 Type: string 例: #ShareExtra |
| fourth_cta_tweet 条件付き必須 | 4 つ目の CTA がクリックされたときに使用する Tweet テキスト。 Type: string 注: fourth_cta が設定されている場合に必須。 例: I Heart @TwitterDev Again |
| unlocked_image_media_key 任意 | インスタントアンロック時に使用する画像の media_key。これは書き込み専用フィールドです。レスポンスでは、この画像の X の URL を API が返します。 注: 画像はアカウントの Media Library に存在している必要があります。 注: 画像の最小幅は 800px、幅:高さのアスペクト比は 5:2 が必要です。 Type: string 例: 3_883112887618682880 |
| thank_you_url 任意 | サンクス文とともに表示する URL。 Type: string 例: 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
例のレスポンス
リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id
パラメータ
| Name | Description |
|---|---|
| account_id required | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_id required | リクエストで操作する画像会話カードを参照する ID。 Type: string Example: 4i0qg |
| first_cta optional | 1 番目のオプションの Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字（#は除く）。 Type: string Example: #ShareNow |
| first_cta_tweet optional | 1 番目の CTA クリック時に使用される Tweet テキスト。 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 クリック時に使用される Tweet テキスト。 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 クリック時に使用される Tweet テキスト。 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 クリック時に使用される Tweet テキスト。 Type: string Note: fourth_cta を設定した場合は必須。 Example: I Heart @TwitterDev Again |
| media_key optional | このカードで使用する画像のメディアキー。 Note: 画像はアカウントの Media Library に存在している必要があります。 Note: 最小画像幅は 800px、アスペクト比（幅:高さ）は 1.91:1 が必要です。 Type: string Example: 3_1151345051104991073 |
| name optional | カード名。 Type: string Example: moon card |
| thank_you_text optional | CTA クリック後に表示されるテキスト。最大長: 23 文字。 Type: string Example: Thank you |
| thank_you_url optional | サンクステキストとともに表示する URL。 Type: string Example: https://example.com/thankyou |
| title optional | 画像の下、CTA の上に表示されるカードのタイトル。最大長: 23 文字。 Type: string Note: second_cta が未設定の場合は必須。 Example: Start a conversation |
| unlocked_image_media_key optional | インスタントアンロック時に使用される画像の media_key。これは書き込み専用フィールドです。レスポンスでは、この画像の X URL が API により返されます。 Note: 画像はアカウントのメディアライブラリに存在している必要があります。 Note: 最小画像幅は 800px、アスペクト比（幅:高さ）は 5:2 が必要です。 Type: string Example: 3_883112887618682880 |
リクエスト例
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card
応答例
リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジド（委任）アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_id 必須 | リクエストで操作対象となる画像コンバージョンカードへの参照。 Type: string Example: 4i0qe |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/4i0qe
レスポンスの例
メディアライブラリ
GET accounts/:account_id/media_library
現在のアカウントに関連するメディアライブラリ内のオブジェクトのうち、一部またはすべての詳細を取得します。リソース URL
https://ads-api.x.com/12/accounts/:account_id/media_library
パラメーター
| Name | Description |
|---|---|
| account_id required | レバレッジドアカウントの識別子。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| count optional | 各リクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 20 Min, Max: 1, 50 |
| cursor optional | 次の結果ページを取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: c-1 |
| media_type optional | レスポンスを希望するメディアタイプのみに絞り込みます。 Type: enum Possible values: GIF, IMAGE, VIDEO |
| q optional | name、title、file_name、description fields によるリソースの絞り込みに使用する任意の query。注: 大文字小文字を区別しない「term」マッチングを行います。 Type: string Min, Max length: 1, 255 |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?count=1
レスポンス例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key
パラメーター
| Name | Description |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| media_key 必須 | リクエストで操作対象となるメディアライブラリ内のオブジェクトを参照するキー。 Type: string Example: 13_909110614026444802 |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/13_909110614026444802
応答例
AMPLIFY_VIDEO メディアカテゴリの動画を Media Library に追加すると、自動的に PREROLL の account_media アセットとして利用可能になります。
リソースURL
https://ads-api.x.com/12/accounts/:account_id/media_library
パラメータ
| Name | Description |
|---|---|
| account_id required | 利用対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| media_key required | アップロード済みコンテンツの media_key。media_category が指定されている場合、POST media/upload のレスポンスで media_key が返されます。 Type: string Example: 3_931236738554519552 |
| description optional | Tweet 時に動画の下に表示される説明。最大 200 文字。 これはデフォルトでは Tweet に表示されません。動画の description を表示するには、POST accounts/:account_id/tweet endpoint で video_description パラメータを使用してください。 Note: 動画でのみ使用できます。 Type: string Example: This is the description under the video. |
| file_name optional | メディアライブラリオブジェクトのファイル名。最大長: 255。 ファイル名は ads.x.com の Media Library UI の各メディアアセットのメディア詳細で確認できます。file_name が設定されていない場合は空になります。 Type: string Example: coffee.jpeg |
| name optional | メディアライブラリオブジェクトの名前。最大長: 100。 これは ads.x.com の Media Library UI における各メディアアセットのラベルです。name が設定されていない場合、ラベルは “Untitled” になります。 Type: string Example: Latte |
| poster_media_key optional | アップロード済み画像の media_key を使用して、動画のポスター画像を指定します。指定しない場合は最初のフレームが使用されます。 Note: 動画でのみ使用できます。 Type: string Example: 3_890599134483242005 |
| title optional | Tweet 時に動画の下に表示されるタイトル（見出し）。最大 70 文字。 これはデフォルトでは Tweet に表示されません。動画の title を表示するには、POST accounts/:account_id/tweet endpoint で video_title パラメータを使用してください。 Note: 動画でのみ使用できます。 Type: string Example: Video title |
リクエスト例
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552
応答例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key
パラメータ
| Name | Description |
|---|---|
| account_id required | 利用対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| media_key required | リクエストで操作するメディアライブラリ内オブジェクトへの参照。 Type: string Example: 16_844800354743074820 |
| description optional | Tweet 時に動画の下に表示される説明。最大 200 文字。既定では Tweet に表示されません。動画の description を表示するには、POST accounts/:account_id/tweet endpoint の video_description パラメータを使用してください。 注意: 動画でのみ使用できます。 Type: string Example: This is the description under the video. |
| file_name optional | メディアライブラリオブジェクトのファイル名。最大長 255。ファイル名は ads.x.com の Media Library UI の各メディアアセットの詳細で確認できます。file_name が未設定の場合は空になります。 Type: string Example: coffee.jpeg |
| name optional | メディアライブラリオブジェクトの名前。最大長 100。ads.x.com の Media Library UI で各メディアアセットのラベルとして表示されます。name が未設定の場合、ラベルは「Untitled」になります。 Type: string Example: Latte |
| poster_media_key optional | アップロード済み画像の media_key を使用して、動画のポスター画像を指定します。 注意: 動画でのみ使用できます。 Type: string Example: 3_885003359340375465 |
| title optional | Tweet 時に動画の下に表示されるタイトル（見出し）。最大 70 文字。既定では Tweet に表示されません。動画の title を表示するには、POST accounts/:account_id/tweet endpoint の 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
応答例
リソースURL
https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| media_key 必須 | リクエストで操作対象となるメディアライブラリ内のオブジェクトを指す参照。 Type: string Example: 7_860318603387600896 |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/7_860318603387600896
レスポンス例
投票カード
GET accounts/:account_id/cards/poll
現在のアカウントに関連付けられた一部またはすべての投票カードの詳細を取得します。リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/poll
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象のアカウントを識別する ID。リソースのパス内に含まれ、GET accounts を除く Advertiser API のすべてのリクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string 例: 18ce54d4x5t |
| card_ids 任意 | 識別子をカンマ区切りで指定して、必要な投票カードのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string 例: 57i77 |
| count 任意 | リクエストごとに取得を試みるレコード数を指定します。 Type: int 既定値: 200 最小, 最大: 1, 1000 |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string 例: 8x7v00oow |
| q 任意 | name によるカードの絞り込みに使用する任意の query。すべてを取得する場合はこのパラメータを省略します。最大長: 80 文字。 注: 大文字小文字を区別しない前方一致で照合します。 Type: string 例: night |
| sort_by 任意 | サポート対象の属性で、昇順または降順に並べ替えます。詳細は Sorting を参照してください。 Type: string 例: created_at-asc |
| with_deleted 任意 | 削除済みの結果を含めます。 Type: boolean 既定値: false 可能な値: true, false |
| with_total_count 任意 | レスポンスに total_count 属性を含めます。 注: このパラメータと cursor は同時指定できません。 注: total_count を含むリクエストはレートリミットが低く、現在は 15 分あたり 200 件に設定されています。 Type: boolean 既定値: false 可能な値: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?card_ids=57i77
応答例
リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id
パラメーター
| Name | Description |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_id 必須 | リクエストで操作対象となる投票カード（poll card）への参照。 Type: string Example: 57i8t |
| with_deleted 任意 | 削除済みの結果を含めるかどうか。 Type: boolean Default: false Possible values: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i8t
応答例
POST accounts/:account_id/cards/poll
指定したアカウントに紐づく新しい投票カードを作成します。このendpointでは、画像付き、動画付き、またはメディアなしの投票カードを作成できます。メディアを含む投票は「Media Forward Polls」と呼ばれます。 Note: 「Media Forward Polls」プロダクトはベータ版で、利用にはPROMOTED_MEDIA_POLLS アカウント機能が必要です。
Note: 投票カードは更新（PUT）できません。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/poll
パラメータ
| Name | Description |
|---|---|
| account_id 必須 | 利用するアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| duration_in_minutes 必須 | 投票を受け付ける時間（分）。指定した duration_in_minutes を過ぎると投票は締め切られ、以降は投票できません。これはレスポンスの end_time に対応します。 注記: カードが作成された時点から開始され、Tweet に追加された時点からではありません。 Type: int Min, Max: 5, 10080 |
| first_choice 必須 | 1つ目の投票選択肢。最大長: 25文字。 Type: string Example: One |
| name 必須 | カード名。 Type: string Example: poll card |
| second_choice 必須 | 2つ目の投票選択肢。最大長: 25文字。 Type: string Example: Two |
| fourth_choice 任意 | 4つ目の投票選択肢。最大長: 25文字。 注記: このパラメータを使用する場合は、1〜3つ目の選択肢を設定しておく必要があります。 Type: string Example: Four |
| media_key 任意 | このカードで使用する、メディアライブラリ内の画像または動画の media_key。これは書き込み専用フィールドです。レスポンスでは、このメディアの X 上のURLが API から提供されます。 注記: 画像または動画はアカウントのメディアライブラリ内に存在している必要があります。 注記: 画像の最小幅は 800px、アスペクト比は 1.91:1 が必要です。 |
| third_choice 任意 | 3つ目の投票選択肢。最大長: 25文字。 注記: このパラメータを使用する場合は、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
例のレスポンス
リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジアカウントの識別子。リソースのパスに含まれ、GET accounts を除く Advertiser API のすべてのリクエストで一般的に必須です。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_id 必須 | リクエストで操作する投票カードを参照します。 Type: string Example: 57i9t |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t
例: レスポンス
プリロールのCTA
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
パラメーター
| Name | Description |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string 例: 18ce54d4x5t |
| line_item_ids 任意 | カンマ区切りの識別子リストを指定して、特定のラインアイテムに関連付けられた preroll CTA のみにレスポンスを絞り込みます。ID は最大 200 まで指定できます。 Type: string 例: 8v53k |
| count 任意 | リクエストごとに取得を試みるレコード数を指定します。 Type: int デフォルト: 200 最小, 最大: 1, 1000 |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string 例: 8x7v00oow |
| preroll_call_to_action_ids 任意 | カンマ区切りの識別子リストを指定して、目的の preroll CTA のみにレスポンスを絞り込みます。ID は最大 200 まで指定できます。 Type: string 例: 8f0 |
| sort_by 任意 | サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string 例: created_at-asc |
| with_deleted 任意 | 削除済みの結果をレスポンスに含めます。 Type: boolean デフォルト: false 取りうる値: true, false |
| with_total_count 任意 | レスポンスに total_count 属性を含めます。 注記: このパラメーターと cursor は同時指定できません。 注記: total_count を含むリクエストはレートリミットが低く、現在は 15 分あたり 200 に設定されています。 Type: boolean デフォルト: false 取りうる値: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_ids=8v53k
応答例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須です。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| preroll_call_to_action_id 必須 | リクエストで操作対象となる preroll call to action への参照。 Type: string Example: 8f0 |
| with_deleted 任意 | 削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0
応答例
POST accounts/:account_id/preroll_call_to_actions
PREROLL_VIEWS ラインアイテムに対して、任意のコールトゥアクション（CTA）を設定します。
リソースURL
https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象のアカウントを示す識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| call_to_action 必須 | 広告に表示されるボタンの CTA テキスト。 Type: enum Possible values: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW |
| call_to_action_url 必須 | CTA ボタンをクリックした際にユーザーを遷移させる URL。 Type: string Example: https://www.x.com |
| line_item_id 必須 | リクエストで操作するラインアイテムの参照。 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
応答例
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 required | 連携先アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| preroll_call_to_action_id required | リクエストで操作対象となるプレロール CTA への参照。 Type: string Example: 8f0 |
| call_to_action optional | 広告内に表示されるボタンのCTAテキスト。 Type: enum Possible values: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW |
| call_to_action_url optional | CTAボタンがクリックされた際にユーザーをリダイレクトするURL。 Type: string Example: https://www.x.com |
リクエスト例
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW
例: レスポンス
リソースURL
https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| preroll_call_to_action_id 必須 | リクエストで操作対象となる preroll CTA への参照。 Type: string Example: 8f0 |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0
応答例
予約済み Tweets
GET accounts/:account_id/scheduled_tweets
現在のアカウントに関連付けられているスケジュール済みTweetの一部またはすべての詳細を取得します。リソースURL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets
パラメーター
| Name | Description |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで基本的に必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| count 任意 | 各リクエストで取得を試みるレコード数を指定します。 Type: int Default: 100 Min, Max: 1, 200 |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: c-j3cn6n40 |
| user_id 任意 | Scheduled Tweets を取得する対象ユーザーを指定します。未設定の場合は、そのアカウントの FULL プロモータブルユーザーが既定値になります。 Type: long Example: 756201191646691328 |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?count=1
応答例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id
パラメーター
| Name | Description |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| scheduled_tweet_id 必須 | リクエストで操作対象となる Scheduled Tweet への参照。 Type: string Example: 917438609065623552 |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552
返答例
POST accounts/:account_id/scheduled_tweets
アカウントのフルプロモート対象ユーザー（デフォルト）またはas_user_id パラメータで指定されたユーザーに対して、予約済みの Tweet を作成します。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets
パラメータ
| Name | Description |
|---|---|
| account_id 必須 | 使用するアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| scheduled_at 必須 | Tweet を公開（ライブ配信）する時刻を ISO 8601 で指定します。 注: 予約できるのは最長で1年先までです。 注: 予約は分単位のみ有効で、秒は無視されます。 Type: string Example: 2017-12-31T23:59:00Z |
| as_user_id 必須 | 代理で Tweet を投稿する広告主のユーザー ID。広告主は ads.x.com から、あなたのハンドル（複数可）に自分の広告アカウントへのアクセス権を付与する必要があります。この権限により、広告主ではなくあなた自身のハンドルの OAuth トークンで API を呼び出せます。 Type: long Example: 756201191646691328 |
| text 場合により必須 | ステータス更新の本文。media_keys が指定されていない場合は必須です。 Type: string Example: just setting up my twttr |
| card_uri 任意 | 利用可能な場合は、カードのレスポンスで得た card_uri の値を使用して Tweet にカードを関連付けます。 Type: string Example: card://855591459410511943 |
| media_keys 任意 | 識別子のカンマ区切りリストを指定して Tweet にメディアを関連付けます。画像は最大4枚、アニメーション GIF は1件、動画は1件まで含められます。 注: メディアアセットはアカウントの Media Library に存在している必要があります。 Type: string Example: 13_1153584529292270722 |
| nullcast 任意 | nullcast（「Promoted-only」）の Tweet を作成するかどうか。 Type: boolean Default: true Possible values: true, false |
| name 任意 | 予約 Tweet の名前。最大長: 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
例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id
パラメーター
| Name | Description |
|---|---|
| account_id required | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| scheduled_tweet_id required | リクエストで操作対象となる Scheduled Tweet への参照。 Type: string Example: 870321875435442177 |
| card_uri optional | 利用可能な場合、任意の cards レスポンスの card_uri の値を使用して Tweet にカードを関連付けます。 Note: 値を指定せずにパラメーターを渡すと未設定（削除）となります。 Type: string Example: card://875146925316386347 |
| media_keys optional | 識別子のカンマ区切りリストを指定して Tweet にメディアを関連付けます。画像は最大4枚、アニメーション GIF は1件、または動画は1件まで含められます。 Note: メディアアセットはアカウントの Media Library に存在している必要があります。 Note: 値を指定せずにパラメーターを渡すと未設定（削除）となります。 Type: string Example: 13_1153584529292270722 |
| nullcast optional | nullcast（「Promoted-only」）Tweet を作成するかどうか。 Type: boolean Possible values: true, false |
| scheduled_at optional | Tweet を公開（配信開始）する時刻。ISO 8601 で表します。 Type: string Example: 2017-12-31T23:59:59Z |
| text optional | ステータス更新の本文。 Type: string Example: just setting up my twttr |
| name optional | Scheduled Tweet の名前。最大長：80文字。 Type: string Example: Tweet with name |
リクエスト例
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice
例: レスポンス
リソース URL
https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに紐づいている必要があります。 Type: string Example: 18ce54d4x5t |
| scheduled_tweet_id 必須 | リクエストで操作する Scheduled Tweet の参照。 Type: string Example: 870321875435442177 |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776
応答例
Tweet プレビュー
GET accounts/:account_id/tweet_previews
公開済み、予約済み、または下書きのTweetをプレビューします。- 1回のAPIリクエストで最大200件までの複数のTweetをプレビュー可能
- Tweetのレイアウトとスタイルを正確かつ最新状態でレンダリング
- 最新のすべてのフォーマットとカードタイプに対応
- iframeを返します
リソース URL
https://ads-api.x.com/12/accounts/:account_id/tweet_previews
パラメーター
| Name | Description |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで基本的に必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| tweet_ids 必須 | ID のカンマ区切りリスト。最大 200 個の ID を指定できます。 注: ID は指定した tweet_type に対応している必要があります。たとえば、Scheduled Tweet の ID を渡して tweet_type=PUBLISHED を指定した場合、その ID のプレビューは返されません。 Type: long Example: 1122911801354510336,1102836745790316550 |
| tweet_type 必須 | 指定した tweet_ids に対応する Tweet の種類。 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
応答例
Tweets
GET accounts/:account_id/tweets
アカウントのフル・プロモート可能ユーザー（デフォルト）またはuser_id パラメーターで指定したユーザーの Tweet の詳細を取得します。対象は、そのアカウント配下のプロモート可能ユーザーのいずれかです。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/tweets
パラメーター
| Name | Description |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string 例: 18ce54d4x5t |
| tweet_type 必須 | 指定した tweet_ids の Tweet の種類。 Type: enum 取り得る値: DRAFT, PUBLISHED, SCHEDULED |
| count 任意 | リクエストごとに取得を試みるレコード数を指定します。 Type: int 既定値: 200 最小, 最大: 1, 1000 |
| cursor 任意 | 次の結果ページを取得するためのカーソル。詳細は Pagination を参照してください。 Type: string 例: AAAAAFhLRpQLNF-sGBSgAA |
| include_mentions_and_replies 任意 | 利用可能な Tweets の一覧からメンションと返信を除外するかどうか。 Type: boolean 既定値: false 取り得る値: true, false |
| name 任意 | name で Tweets の範囲を絞り込むための任意の query。すべて取得する場合はこのパラメーターを省略します。最大長: 80 文字。 注: 大文字小文字を区別しない前方一致でマッチングします。 Type: string 例: dtc |
| timeline_type 任意 | nullcast（「Promoted-only」）の Tweets、オーガニックの Tweets、または両方を返すかどうか。 Type: enum 既定値: NULLCAST 取り得る値: ALL, NULLCAST, ORGANIC |
| trim_user 任意 | Tweet レスポンスからユーザーオブジェクトを除外するかどうか。有効にすると、返されるユーザーオブジェクトはその Tweet の投稿者のユーザー ID のみになります。 Type: boolean 既定値: false 取り得る値: true, false |
| tweet_ids 任意 | ID のカンマ区切りリスト。最大 200 個まで指定できます。 注: 各 ID は指定した tweet_type に対応している必要があります。例えば Scheduled Tweet の ID を渡す場合、レスポンスにその Tweet を含めるには tweet_type を SCHEDULED にする必要があります。 Type: long 例: 1122911801354510336,1102836745790316550 |
| user_id 任意 | Tweets の対象ユーザーを指定します。未指定の場合、アカウント上の FULL のプロモータブルユーザーが既定となります。 Type: long 例: 756201191646691328 |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets?tweet_ids=1166476031668015104&tweet_type=PUBLISHED&trim_user=true
応答例
POST accounts/:account_id/tweet
アカウントの「完全（FULL）」なプロモート可能ユーザー（デフォルト）またはas_user_id パラメータで指定したユーザーとして、Tweet を作成します。nullcast（デフォルト）およびオーガニックの Tweet 作成をサポートします。nullcast された Tweet はパブリックタイムラインに表示されず、フォロワーにも配信されません。どちらのタイプもキャンペーンで使用できます。
認証済みユーザーがこのアカウントの「FULL」プロモート可能ユーザーでない場合は、GET accounts/:account_id/authenticated_user_access endpoint にリクエストし、当該ユーザーの代理で Tweet する権限があるか確認してください。TWEET_COMPOSER の権限がある場合、この endpoint を使用して「FULL」プロモート可能ユーザーの代理で nullcast の Tweet を作成できます。
メディアで upload.x.com の endpoint を使用する場合は、この endpoint に渡す as_user_id の値と同じ user_id を、additional_owners パラメータに指定してください。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/tweet
パラメーター
| Name | Description |
|---|---|
| account_id required | 利用するアカウントの識別子。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| as_user_id required | 代理でTweetを投稿する広告主のユーザーID。広告主は ads.x.com を通じて、あなたのハンドル（1つまたは複数）に自分の広告アカウントへのアクセスを付与する必要があります。この権限により、広告主のものではなくあなた自身のハンドルの OAuth トークンで API を呼び出せます。 Type: long Example: 756201191646691328 |
| text sometimes required | ステータス更新のテキスト。media_keys が指定されていない場合は必須です。 Type: string Example: hello, world |
| card_uri optional | 利用可能な場合、任意のカードのレスポンスから取得した card_uri を使用して Tweet にカードを関連付けます。 Type: string Example: card://853503245793641682 |
| conversation_settings optional | この Tweet に返信できる相手を選択します。メンションされたユーザーは常に返信できます。 Note: このフィールドは POST リクエストのレスポンスでは返されず、GET リクエスト時に返されます。 Note: このパラメーターは Ads API v8 以降でのみ有効です。 Type: enum Default: EVERYONE Possible values: EVERYONE, FOLLOWING, MENTIONED_USERS |
| media_keys optional | 識別子のカンマ区切りリストを指定して Tweet にメディアを関連付けます。画像は最大4枚、アニメーションGIFは1件、動画は1件まで含められます。 Type: string Example: 13_1153584529292270722 |
| name optional | Tweet の名称。最大80文字。 Type: string Example: Tweet with name |
| nullcast optional | nullcast（「Promoted-only」）の Tweet を作成するかどうか。 Note: オーガニックな Tweet（nullcast=false）は認証済みユーザーに対してのみ作成できます。 Type: boolean Default: true Possible values: true, false |
| trim_user optional | Tweet レスポンスにユーザーオブジェクトを含めないかどうか。有効にすると、返されるユーザーオブジェクトはTweetの作成者のユーザーIDのみになります。 Type: boolean Default: false Possible values: true, false |
| tweet_mode optional | レスポンスを互換モードか拡張モードにするか。詳細はこちらを参照してください。 Type: string Possible values: compat, extended |
| video_cta optional | 動画のCTA。 Type: enum Possible values: VISIT_SITE, WATCH_NOW |
| video_cta_value optional | 動画上の対応するCTAの値。 Type: string Example: https://dev.x.com |
| video_description optional | 動画の下に表示される説明。最大200文字。 Type: string Example: Integrate with the X advertising platform |
| video_title optional | 動画の下に表示されるタイトル（見出し）。最大70文字。 Type: string Example: X Ads API |
リクエスト例
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet?text=hello, world&as_user_id=756201191646691328&trim_user=true
応答例
name を更新します。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/tweets/:tweet_id/name
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | 使用するアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| tweet_id 必須 | 当該リクエストで操作対象となる Tweet への参照。 Type: long Example: 994747471329873920 |
| name 任意 | Tweet の名称。最大 80 文字。 Type: string Example: Tweet with name |
リクエスト例
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets/994747471329873920/name?name=new Tweet name
レスポンスの例
Video Conversation Cards
card_uri パラメータを使用し、POST accounts/:account_id/tweet、POST statuses/update、または POST accounts/:account_id/scheduled_tweets のいずれかの endpoint を使用してください。
GET accounts/:account_id/cards/video_conversation
現在のアカウントに関連付けられている一部またはすべての動画会話カードの詳細を取得します。リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation
パラメータ
| Name | Description |
|---|---|
| account_id 必須 | 対象のアカウントを識別する ID。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string 例: 18ce54d4x5t |
| card_ids 任意 | 目的の動画会話カードに結果を絞り込むには、カンマ区切りの ID リストを指定します。最大 200 個まで指定できます。 Type: string 例: 5a86h |
| count 任意 | リクエストごとに取得を試みるレコード数を指定します。 Type: int デフォルト: 200 最小, 最大: 1, 1000 |
| cursor 任意 | 次の結果ページを取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string 例: 8x7v00oow |
| q 任意 | name によるカードの絞り込みに使用する任意の query。すべてを取得する場合はこのパラメータを省略します。最大長: 80 文字。 注: 大文字小文字を区別しない前方一致でマッチします。 Type: string 例: night sky |
| sort_by 任意 | サポートされる属性で昇順または降順に並べ替えます。詳細は Sorting を参照してください。 Type: string 例: created_at-asc |
| with_deleted 任意 | 削除済みの結果を含めます。 Type: boolean デフォルト: false 取りうる値: true, false |
| with_total_count 任意 | total_count レスポンス属性を含めます。 注: このパラメータと cursor は同時指定できません。 注: total_count を含むリクエストはレートリミットが低くなり、現在は 15 分あたり 200 に設定されています。 Type: boolean デフォルト: false 取りうる値: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?card_ids=5a86h
応答例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id
パラメーター
| Name | Description |
|---|---|
| account_id required | 対象アカウントの識別子。リソースパスに含まれ、GET accounts を除く Advertiser API の全リクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_id required | リクエストで操作対象となる video conversation card への参照。 Type: string Example: 4i0ya |
| with_deleted optional | 削除済みの結果を含めるかどうか。 Type: boolean Default: false Possible values: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h
応答例
POST accounts/:account_id/cards/video_conversation
指定されたアカウントに関連付けられた新しいビデオ会話カードを作成します。 当社のendpointでの画像アップロードに関する有用な情報は、Uploading Mediaを参照してください。リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての広告主向けAPIリクエストで原則として必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。Type: string 例: 18ce54d4x5t |
| first_cta 必須 | 1つ目のオプション用のCTA（Call-To-Action）ハッシュタグ。最大長: 20文字（#は文字数に含めない）。Type: string 例: #APIs |
| first_cta_tweet 必須 | 1つ目のCTAがクリックされたときに使用されるTweetテキスト。Type: string 例: Ads API |
| media_key 必須 | このカードで使用する動画のメディアキー。注意: 動画はアカウントのMedia Library に存在する必要があります。注意: アスペクト比は16:9が必須です。Type: string 例: 13_1168079965037467209 |
| name 必須 | カードの名前。Type: string 例: video conversation card |
| thank_you_text 必須 | CTAクリック後に表示されるテキスト。最大長: 23文字。Type: string 例: Build it |
| title 状況により必須 | 動画の下、CTAの上に表示されるカードのタイトル。最大長: 23文字。Type: string 注意: second_cta が設定されていない場合は必須。例: Developers |
| second_cta 状況により必須 | 2つ目のオプション用のCTAハッシュタグ。最大長: 20文字（#は文字数に含めない）。Type: string 注意: title が設定されていない場合は必須。例: #ShareAgain |
| second_cta_tweet 状況により必須 | 2つ目のCTAがクリックされたときに使用されるTweetテキスト。注意: second_cta が設定されている場合は必須。Type: string 例: I Heart @AdsAPI Again |
| poster_media_key 任意 | このカードで使用するポスター画像のメディアキー。未指定の場合は最初のフレームが使用されます。注意: 動画はアカウントのMedia Library に存在する必要があります。Type: long 例: 3_882726458191298561 |
| third_cta 任意 | 3つ目のオプション用のCTAハッシュタグ。最大長: 20文字（#は文字数に含めない）。Type: string 例: #ShareMore |
| third_cta_tweet 状況により必須 | 3つ目のCTAがクリックされたときに使用されるTweetテキスト。Type: string 注意: third_cta が設定されている場合は必須。例: I Heart @TwitterDev |
| fourth_cta 任意 | 4つ目のオプション用のCTAハッシュタグ。最大長: 20文字（#は文字数に含めない）。Type: string 例: #ShareExtra |
| fourth_cta_tweet 状況により必須 | 4つ目のCTAがクリックされたときに使用されるTweetテキスト。Type: string 注意: fourth_cta が設定されている場合は必須。例: I Heart @TwitterDev Again |
| thank_you_url 任意 | サンクステキストと共に表示されるURL。Type: string 例: https://example.com/thankyou |
| unlocked_image_media_key 任意 | インスタントアンロックのシナリオで使用される画像のmedia_key。このフィールドは書き込み専用です。レスポンスでは、この画像のXのURLがAPIから返されます。注意: 画像はアカウントのメディアライブラリに存在する必要があります。Type: string 例: 3_883112887618682880 |
| unlocked_video_media_key 任意 | インスタントアンロックのシナリオで使用される、GET accounts/:account_id/media_library endpoint から取得した動画の識別子。Type: string 例: 13_867520357225418752 |
リクエスト例
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?first_cta=#APIs&first_cta_tweet=Ads API&name=video conversation card&thank_you_text=Build it&title=Developers&media_key=13_958388276489895936
例のレスポンス
リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。種類: string 例: 18ce54d4x5t |
| card_id 必須 | リクエストで操作対象となる動画会話カードを指す参照。種類: string 例: 5a86h |
| first_cta 任意 | 1 番目の選択肢の Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字（# はカウントしません）。種類: string 例: #APIs |
| first_cta_tweet 任意 | 1 番目の CTA クリック時に使用される Tweet テキスト。種類: string 例: Ads API |
| second_cta 任意 | 2 番目の選択肢の Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字（# はカウントしません）。種類: string 注意: title が設定されていない場合は必須。例: #ShareAgain |
| second_cta_tweet 任意 | 2 番目の CTA クリック時に使用される Tweet テキスト。注意: second_cta が設定されている場合は必須。種類: string 例: I Heart @AdsAPI Again |
| third_cta 任意 | 3 番目の選択肢の Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字（# はカウントしません）。種類: string 例: #ShareMore |
| third_cta_tweet 任意 | 3 番目の CTA クリック時に使用される Tweet テキスト。種類: string 注意: third_cta が設定されている場合は必須。例: I Heart @TwitterDev |
| fourth_cta 任意 | 4 番目の選択肢の Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字（# はカウントしません）。種類: string 例: #ShareExtra |
| fourth_cta_tweet 任意 | 4 番目の CTA クリック時に使用される Tweet テキスト。種類: string 注意: fourth_cta が設定されている場合は必須。例: I Heart @TwitterDev Again |
| media_key 任意 | このカードで使用する動画のメディアキー。注意: 動画はアカウントの Media Library に存在している必要があります。注意: アスペクト比 16:9 が必須です。種類: string 例: 13_1168079965037467209 |
| name 任意 | カードの名前。種類: string 例: developers card |
| poster_media_key 任意 | このカードで使用するポスター画像のメディアキー。指定しない場合は最初のフレームが使用されます。注意: 動画はアカウントの Media Library に存在している必要があります。種類: long 例: 3_882726458191298561 |
| thank_you_text 任意 | CTA クリック後に表示されるテキスト。最大長: 23 文字。種類: string 例: Build it |
| thank_you_url 任意 | サンクス文と一緒に表示される URL。種類: string 例: https://example.com/thankyou |
| title 任意 | 動画の下、CTA の上に表示されるカードのタイトル。最大長: 23 文字。種類: string 注意: second_cta が設定されていない場合は必須。例: Start a conversation |
| unlocked_image_media_key 任意 | インスタントアンロックのシナリオで使用される画像の media_key。これは書き込み専用フィールドです。レスポンスでは、この画像に対する X の URL が API から提供されます。注意: 画像はアカウントのメディアライブラリに存在している必要があります。種類: string 例: 3_883112887618682880 |
| unlocked_video_media_key 任意 | インスタントアンロックのシナリオで使用される、GET accounts/:account_id/media_library endpoint の動画の識別子。種類: string 例: 13_867520357225418752 |
リクエスト例
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h?name=developers card
応答例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除く Advertiser API のすべてのリクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| card_id 必須 | リクエストで操作する video conversation card への参照。 種別: string 例: 4i0ya |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/4i0ya