概要
- 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
- 動画アプリダウンロード: 16:9、1:1
- 投票: 16:9
- 動画会話: 16:9
- 動画ダイレクトメッセージ: 16:9
プロモーテッド動画
media_id を用いて POST accounts/:account_id/videos エンドポイントから動画を広告アカウントに関連付けます。動画の id（media_key と呼ばれることもあります）は以降のリクエストで使用します。これは、先頭が整数、続いてアンダースコア、末尾が長い値という形式の文字列です。例: 13_875943225764098048。
ツイート内のプロモ動画
id とともに POST accounts/:account_id/tweet エンドポイントを使用します。この段階で、動画のタイトル、説明、CTA（コールトゥアクション）も指定できます。これらの値はユーザーに表示されます。
カードのプロモーション動画
- 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 エンドポイントで Tweet を作成します。カードは card_uri パラメータを使用して Tweet に添付します。
一般情報
- （2015-10-22 時点）プロモーション用コンテンツで使用する動画をアップロードする場合は、POST media/upload (chunked) エンドポイントへのすべての
INITコマンドリクエストで、media_categoryパラメータにamplify_videoを指定する必要があります。この新しいパラメータを使用すると、動画が非同期で事前処理され、プロモーション用コンテンツで利用できる状態に準備されます。アップロード後の非同期処理の完了状況はSTATUSコマンドで確認できます。 - 現在許可されているプロモーション動画の最大長は 10 分、ファイルサイズは 500MB 以下です。
- アップロードする動画は mp4 または mov を使用してください。
- アップロードされた動画の処理は通常は速やかに行われますが、処理時間は動画の長さやファイルサイズによって変動します。
- アップロードするポスター画像は png または jpg 形式を使用してください。アスペクト比やサイズの要件はありませんが、ポスター画像はビデオプレーヤーに合わせて調整されます。
ガイド
予約投稿のTweet
はじめに
- 新規にスケジュールされた Tweet の作成、変更、表示
- スケジュールされた Tweet をラインアイテムに関連付ける
- 既存のスケジュールされた Tweet のクエリおよび管理
- スケジュールされた Tweet が公開された後、公開された Tweet の
idを取得
API エンドポイント
予約済み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をプレビュー）
予約済みプロモートTweet
- GET accounts/:account_id/scheduled_promoted_tweets（すべての予約済みプロモートTweetの一覧を取得）
- GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id（
idを使用して予約済みプロモートTweetを参照） - POST accounts/:account_id/scheduled_promoted_tweets（新しい予約済みプロモートTweetを作成）
- DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id（
idを使用して既存の予約済みプロモートTweetを削除）
予約済み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 が両方含まれている場合、その予約済みの Tweet は公開されず、scheduled_status は FAILED に設定されます
ワークフロー
text とあわせて scheduled_at の時刻です。さらに、このエンドポイントでは、as_user_id パラメータを使って別の @handle を代理してスケジュール済みTweetを作成したり、カード（card_uri）やメディア（media_ids）を追加したりできるいくつかのオプションも提供しています。なお、1つのTweetに含められるエンティティは同一タイプのみです。つまり、Video、Gif、または Image のいずれかです。nullcast パラメータは、そのTweetが「Promoted-Only」Tweetかどうかを制御します。新規に作成されるスケジュール済みTweetはデフォルトで「Promoted-Only」（nullcast=true）です。nullcast=false の場合はオーガニックなスケジュール済みTweetが作成されます。
スケジュール済みTweetが正常に作成されると、レスポンスには当該スケジュール済みTweet自体の一意の識別子である id フィールドが含まれます。これに加えて、tweet_id というフィールドも返されます。このフィールドは当初は null ですが、Tweet が公開されると「ライブ」なTweetのIDで更新されます。
tweet_id フィールドに「公開中」のTweetのIDが設定されます。
Scheduled Tweetを表示
GET accounts/:account_id/tweet_previews エンドポイントに、前の手順で取得したScheduled Tweetの id を指定すると、Tweetのプレビューを生成できます。APIレスポンスには、Scheduled Tweetのプレビューをそのまま表示するために使用できる iframe のURLが含まれます。関連するCSSと画像はXから直接配信されます。
nullcast=true）のTweetを作成することもでき、いずれもラインアイテムに関連付け可能です。これを実現するために、POST accounts/:account_id/scheduled_promoted_tweets エンドポイントも提供しています。このエンドポイントでは、1回のAPIコールで1つのPromoted Scheduled Tweetのみをラインアイテムに関連付けられます。同じラインアイテムに複数のScheduled Tweetを関連付けるには、複数回のAPIコールが必要です。
既存のScheduled Promoted Tweetは変更できませんのでご注意ください。
SCHEDULED状態であること、また指定の目的に対して有効であることは検証しますが、それ以外の検証は行いません。ラインアイテムおよびScheduled Tweetに適用される残りの検証ルールは、Tweetが「ライブ」になる際に実行されます。
キャンペーン配信に問題が生じないよう、Scheduled Tweetはキャンペーン／ラインアイテムのフライト開始前の時刻にscheduled_atされることを推奨します。
たとえば、Scheduled Tweetがキャンペーン開始日より後にライブになるよう設定されている（かつ単一のラインアイテムに単一のTweetのみが関連付けられている）場合、キャンペーンはACTIVEとなりますが、Scheduled Tweetがまだライブではないため、配信可能なクリエイティブは存在しません。
Scheduled Tweetの管理
以下のエンドポイント群により、API利用者はすべてのScheduled TweetおよびScheduled Promoted Tweetを管理できます。これらのAPIは、指定した状態での任意のフィルタリングを伴うScheduled Tweetの一覧を返すこと、ならびに指定のScheduled Tweetをそのidで検索することに使用できます。
スケジュール済みTweetが公開されるとどうなりますか？
scheduled_at の時刻になると、次の更新が行われます。
- 「公開中」のTweetが作成されますが、最大1秒の遅延が生じる場合があります
tweet_idが次のエンティティに追加されます:- スケジュール済みTweet
- プロモーション用スケジュール済みTweet
- 新しいプロモーション用Tweetエンティティが作成されます
ベストプラクティス
- Scheduled Tweet を作成する際は、Tweet が有効であることを確認してください（例：Tweet には Image、Video、Gif のいずれか一つのみを含めることができ、3つを組み合わせることはできません）
- キャンペーンのフライト期間（
start_timeとend_time）が Scheduled Tweet のscheduled_at時刻と整合していることを確認してください - Scheduled Tweets を、現在から1年（365日）を超える日時に設定しないでください
- Scheduled Tweets の Tweet プレビューは現在サポートされていません（作成前に Scheduled Tweets をプレビューする機能）
メディア ライブラリ
はじめに
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 の特定
カードの URI 値で作成された Tweet の場合は、card_uri のレスポンス属性にあるカードへの参照を確認します。以下の例のレスポンスは、GET accounts/:account_id/tweets エンドポイントを使用しています。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 | 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 |
| 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 に単一画像が含まれるか複数画像が含まれるかによって異なります。
動画
| リソース | 識別子 | 属性 |
|---|---|---|
| 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_content_id というレスポンス属性が含まれますが、返される値の型に一貫性がありません。メディアIDの場合もあれば、メディアキーの場合もあります。
動画のURLへのアクセス方法は以下のとおりです。
| リソース | 属性 | 形式 |
|---|---|---|
| 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_url と video_hls_url のレスポンス属性が含まれます。
メディアライブラリ
メディアアセットに関する追加情報が必要になる場合があります。動画カードのユースケースとしては、vmap ではなく mp4 のURLを取得することが挙げられます。これはメディアライブラリで利用できます。取得可能な情報の詳細は Media Library Guideをご参照ください。広告アカウントの FULL プロモート可能ユーザーに属するほとんどのアセットはライブラリで見つかりますが、いくつか例外があります。 メディアの取得 前述のとおり、画像カードには media ID や media key への参照が含まれていません。したがって、メディアライブラリ経由でそれらのアセットを取得することはできません。これはAccount Media の画像にも当てはまります。 動画カードは、作成前に動画アセットがメディアライブラリ（またはその前身の Videos リソース）に登録されている必要があります。したがって、これらのアセットは常にメディアライブラリで取得可能です。これは Account Media の PREROLL アセットにも当てはまります。 最後に、Tweet 内のメディアは必ずメディアライブラリに存在します。 次の表は、検索に使用する識別子がリソースのレスポンスに含まれるかどうかも踏まえて、どのアセットがメディアライブラリで取得可能かをまとめたものです。| Resource | In the Media Library |
|---|---|
| 画像カード | No |
| 動画カード | Yes* |
| Tweets（任意のメディア）** | Yes |
| 予約済みの Tweet | Yes |
| 下書きの Tweet | Yes |
| Account Media の画像 | No |
Account Media の動画（PREROLL） | Yes |
video_content_idがメディアキーであるカードの場合。値がメディアIDの場合でもアセットはメディアライブラリに存在しますが、取得するには数値のプレフィックスとアンダースコアを付与する必要があります。 ** Tweet はメディアIDのみを返します。アセットがメディアライブラリに存在することは保証されていますが、取得には数値のプレフィックスとアンダースコアの付与が必要です。
- AMPLIFY_VIDEO アセットがメディアライブラリに追加されると、PREROLL のクリエイティブタイプとして自動的に Account Media アセットに追加されます。
- 特定の寸法の画像（enumerations page の「Creative Types」を参照）がメディアライブラリに追加されると、自動的に Account Media アセットとして追加されます。クリエイティブタイプ（例：INTERSTITIAL）は画像の寸法によって決まります。
Tweet
はじめに
Nullcasted Tweets
Tweet のプロモーション
Tweet ID
カルーセル
はじめに
Tweet で使用でき、その Tweet をプロモーションできます。ワークフローはこれまで通り同じです。
- メディアをアップロード
- カードを作成
Tweetを作成Tweetをプロモーション
エンドポイント
JSON POST 本文
- メディアキーの配列を受け取る
SWIPEABLE_MEDIAコンポーネントを1つ - 次のうち「いずれか」1つ:
- ウェブサイト情報を指定する
DETAILSコンポーネント - アプリ情報を指定する
BUTTONコンポーネント
SWIPEABLE_MEDIA コンポーネントには、2〜6個の画像または動画を指定できる media_keys 配列を含める必要があります。渡されたメディアキーの順序が、表示順を決定します。
| ウェブサイト | アプリ | |
|---|---|---|
| コンポーネントタイプの指定 | "type": "DETAILS" | "type": "BUTTON" |
| タイトル/ラベル | "title": "X" | "label": { "type": "ENUM", "value": "INSTALL" } |
| 遷移先 | "destination": { "type": "WEBSITE", "url": "https://www.x.com" } | "destination": { "type": "APP", ... } |
BUTTON コンポーネント内のアプリ宛先オブジェクトには、国コードと少なくとも1つのアプリ識別子が必要です。オプションでディープリンクを指定できます。これらの fields の説明については、リファレンスドキュメントを参照してください。
以上を踏まえ、以下にアプリカルーセルの JSON POST ボディ例を示します。
例
media_type リクエストパラメータを使用して、結果を特定のメディアタイプに絞り込みます。
card_uri が含まれており、Tweet を作成する際に使用します。
Tweet
Tweet を作成するには、POST accounts/:account_id/tweet エンドポイントを使用します。前のリクエストで取得した card_uri を使用してください。（可読性のため、レスポンスは一部省略しています。）
クリエイティブメタデータのタグ付け
はじめに
クリエイティブアセットへのタグ付け
exiftool -contributor="<YOUR APP ID>" -creative_file.jpg
exiftool -date="<date>" -creative_file.jpg
アプリ id は 開発者ポータル の「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
パラメーター
| 名前 | 説明 |
|---|---|
| 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 任意 | 指定したクリエイティブタイプに一致するアカウントメディアのみにレスポンスを絞り込みます。複数のクリエイティブタイプは enum 値をカンマ区切りで指定できます。 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
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須のパラメータです。指定したアカウントは認証済みユーザーに紐づいている必要があります。 型: string 例: 18ce54d4x5t |
| account_media_id 必須 | このリクエストで操作対象とするアカウントメディアへの参照。 型: string 例: 2pnfd |
| with_deleted 任意 | 削除済みの結果をレスポンスに含めます。 型: 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
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| account_media_id 必須 | リクエストで操作するアカウントメディアへの参照。 種別: string 例: 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 のいずれかのエンドポイントで使用してください。
現在のアカウントに関連付けられているカードの一部またはすべての詳細を取得します。
注: これは POST accounts/:account_id/cards エンドポイントで作成されたカードのみを返します。その他のエンドポイントで作成されたカードは返されません。
リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| card_types 任意 | カンマ区切りの enum 値のリストを指定して、目的のカードタイプのみにレスポンスを絞り込みます。 種別: 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 任意 | カンマ区切りの識別子リストを指定して、目的のカードのみにレスポンスを絞り込みます。カード ID は最大 200 個まで指定できます。 種別: string 例: 1044294149527166979,1044301099031658496 |
| card_uris 任意 | カンマ区切りの識別子リストを指定して、目的のカードのみにレスポンスを絞り込みます。カード URI 値は最大 200 個まで指定できます。 種別: string 例: card://1044294149527166979,card://1044301099031658496 |
| count 任意 | 各リクエストで取得を試みるレコード数を指定します。 種別: int 既定値: 100 最小/最大: 1 / 200 |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 種別: string 例: 8x7v00oow |
| include_legacy_cards 任意 | レスポンスにレガシーの website および app カードを含めます。レガシーカードとは、リソース URL が accounts/:account_id/cards/:card_type の形式のものを指します。詳細は この開発者フォーラムの投稿 を参照してください。 種別: boolean 既定値: false 取りうる値: true, false |
| q 任意 | name でカードを絞り込むための任意のクエリ。すべて取得するにはこのパラメータを省略します。最大長: 80 文字。 注意: 大文字小文字を区別しない前方一致でマッチします。 種別: string 例: dtc |
| sort_by 任意 | サポートされている属性で昇順または降順に並べ替えます。詳細は Sorting を参照してください。 種別: string 例: created_at-asc |
| with_deleted 任意 | 削除済みの結果を含めます。 種別: 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 リクエストで原則必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| card_id 必須 | カードのid。 種別: string 例: 1044294149527166979 |
| with_deleted 任意 | 削除済みの結果をレスポンスに含めます。 種別: boolean 既定値: false 可能な値: 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 ガイドを参照してください。
リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards
パラメータ
JSON の POST 本文には、カードの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 フィールドを必ず含める必要があります。Ads API では、メディア系コンポーネントと説明系コンポーネントに分類された次のコンポーネントタイプをサポートしています。
- メディア:
MEDIA: 単一の動画または画像SWIPEABLE_MEDIA: 2〜6 本の動画または画像- 説明:
DETAILSBUTTON
type キーに加えて）必須の fields があります。これらは次の表にまとめています。
コンポーネントの 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 またはモバイルアプリを持ちます。
ラベル
ラベルはボタンに表示されるテキストを定義するため、BUTTON コンポーネントにのみ適用されます。ラベルオブジェクトには必須キーが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 | ユーザーをリダイレクトするWebサイトの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 のアプリケーションパッケージ名。 注記: 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 アプリへのディープリンク。 注記: 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
パラメータ
JSON の POST ボディには、更新するパラメータを必ず含めてください。リクエストは、ペイロード内で指定されたパラメータで各フィールドを置き換えます。コンポーネントはオブジェクトとして表され、カードの広告主向け属性を記述します。 次の例は、ペイロードの一般的な構造を示しています（ただし、実際には動作しない情報が含まれます）。| 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 |
リクエスト例
この例では、上記の例の components フィールドで name を更新し、さらに media_keys のうち 1 つを削除します。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
応答例
カードの取得
card_uri を指定して取得します。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/all
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_uris 必須 | 識別子のカンマ区切りリストを指定して、レスポンスを目的のカードのみに絞り込みます。カード URI は最大 200 個まで指定できます。 Type: string Example: card://1044294149527166979,card://1044301099031658496 |
| with_deleted 任意 | 削除済みの結果を含めるかどうか。 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 Example: 18ce54d4x5t |
| card_id 必須 | リクエストで操作対象となるカードを参照します。 Type: string Example: 508pf |
| with_deleted 任意 | 削除済みの結果を含めます。 Type: boolean Default: false Possible values: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all/508pf
応答例
下書きのTweet
GET accounts/:account_id/draft_tweets
現在のアカウントに紐づく Draft Tweets の詳細を、一部またはすべて取得します。リソース URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 活用中のアカウントを識別する ID。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで基本的に必須です。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| count 任意 | リクエストごとに取得を試みるレコード数を指定します。 種別: int 既定値: 100 最小/最大: 1 / 200 |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 種別: string 例: c-jh1g0ryb |
| user_id 任意 | Draft Tweets を取得する対象ユーザーを指定します。未設定の場合、アカウントのプロモート対象ユーザーのうち FULL が既定になります。 種別: string 例: 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 リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに紐づいている必要があります。 型: string 例: 18ce54d4x5t |
| draft_tweet_id 必須 | リクエストで操作する Draft Tweet への参照。 型: string 例: 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
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| as_user_id 必須 | 代理でTweetを投稿する広告主のユーザーID。広告主は ads.x.com を通じて、あなたのハンドル（または複数のハンドル）に自分の広告アカウントへのアクセス権を付与する必要があります。この権限により、広告主のものではなく自分のハンドルの OAuth トークンを使って API を呼び出すことができます。 種別: string 例: 756201191646691328 |
| text 場合により必須 | ステータス更新のテキスト。media_keys が指定されていない場合は必須です。 種別: string 例: Just setting up my X. |
| card_uri 任意 | 利用可能な場合、任意の cards レスポンスの card_uri の値を使用して Tweet にカードを関連付けます。 種別: string 例: card://960880280705392541 |
| media_keys 任意 | 識別子のカンマ区切りリストを指定して、Tweet にメディアを関連付けます。画像は最大4枚、アニメーションGIFは1つ、または動画は1つまで含められます。 注: メディアアセットはアカウントの Media Library に存在している必要があります。 種別: string 例: 13_1153584529292270722 |
| nullcast 任意 | nullcast（「Promoted-only」）の Tweet を作成するかどうか。 種別: boolean 既定値: true 取りうる値: true, false |
| name 任意 | 下書き Tweet の名前。最大: 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.
レスポンスの例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t |
| draft_tweet_id 必須 | リクエストで操作する Draft Tweet への参照。 型: string 例: 994747471329873920 |
| card_uri 任意 | 利用可能な場合、任意の cards レスポンスの card_uri 値を使用して Tweet にカードを関連付けます。 注意: 値を指定せずにパラメーターのみ指定すると未設定（削除）になります。 型: string 例: card://970582057284129151 |
| media_keys 任意 | 識別子をカンマ区切りで指定して、Tweet にメディアを関連付けます。画像は最大 4 枚、アニメーション GIF は 1 件、または動画は 1 件まで含められます。 注意: メディアアセットはアカウントの Media Library に存在している必要があります。 注意: 値を指定せずにパラメーターのみ指定すると未設定（削除）になります。 型: string 例: 13_1153584529292270722 |
| nullcast 任意 | nullcast（「Promoted-only」）Tweet を作成するかどうか。 型: boolean 可能な値: true, false |
| text 任意 | ステータス更新のテキスト。 型: string 例: just setting up my twttr |
| name 任意 | Draft Tweet の名称。最大長: 80 文字。 型: string 例: 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 リクエストで一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| draft_tweet_id 必須 | リクエストで操作する Draft Tweet への参照。 種別: string 例: 994787835663155200 |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200
応答例
POST accounts/:account_id/draft_tweets/preview/:draft_tweet_id
モバイルデバイスで下書きのTweetをプレビューします。 リクエストが成功すると、認証済みユーザーがログインしているすべてのデバイスに通知が送信されます。通知をタップするとタイムラインが開き、ユーザーは下書きのTweetを確認・操作でき、自動再生、音量、全画面表示、動画ウェブサイトカードのドッキングなどの挙動をテストできます。 注: デバイス上でのプレビューは、通知を受け取った本人にのみ表示されます。 注: 通知はXの公式アプリにのみ送信されます。リソース URL
https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_id
パラメータ
| Name | Description |
|---|---|
| account_id required | 対象のアカウントを識別する ID。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須です。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| draft_tweet_id required | このリクエストで対象とする 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 エンドポイントのいずれかを使用してください。
GET accounts/:account_id/cards/image_conversation
現在のアカウントに関連付けられている Image Conversation Card の一部またはすべての詳細を取得します。リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t |
| card_ids 任意 | 必要な画像会話カードのみに対象を絞るため、識別子をカンマ区切りで指定します。最大 200 個の ID を指定できます。 型: string 例: 59woh |
| count 任意 | リクエストごとに取得を試みるレコード数を指定します。 型: int デフォルト: 200 最小/最大: 1/1000 |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 型: string 例: 8x7v00oow |
| q 任意 | name でカードを絞り込むための任意のクエリ。省略するとすべてを取得します。最大長: 80 文字。 注: 大文字小文字を区別しない前方一致で検索します。 型: string 例: night |
| sort_by 任意 | サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。 型: string 例: created_at-asc |
| with_deleted 任意 | 削除済みの結果を含めます。 型: boolean デフォルト: false 可能な値: true, false |
| with_total_count 任意 | レスポンスに total_count 属性を含めます。 注: このパラメーターと cursor は同時指定できません。 注: total_count を含むリクエストはレート制限が低く、現在は 15 分あたり 200 件に設定されています。 型: boolean デフォルト: false 可能な値: 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
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_id 必須 | リクエストで操作する image conversation card への参照。 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
例示的なレスポンス
POST accounts/:account_id/cards/image_conversation
指定したアカウントに紐づく新しい Image Conversation カードを作成します。 エンドポイントへの画像アップロードに関する詳細は、Uploading Media を参照してください。リソースURL
https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation
パラメーター
| Name | Description |
|---|---|
| account_id 必須 | 連携先アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| first_cta 必須 | 1 番目のオプションの Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字（# はカウントしない）。 種別: string 例: #ShareNow |
| first_cta_tweet 必須 | 1 番目の CTA がクリックされたときに使用する Tweet のテキスト。 種別: string 例: I Heart @AdsAPI |
| media_key 必須 | このカードで使用する画像のメディアキー。 注: 画像はアカウントの Media Library に存在している必要があります。 注: 画像の最小幅は 800px、幅:高さのアスペクト比は 1.91:1 が必要です。 種別: string 例: 3_1151345051104991073 |
| name 必須 | カードの名称。 種別: string 例: image conversation card |
| thank_you_text 必須 | CTA クリック後に表示されるテキスト。最大長: 23 文字。 種別: string 例: Thank you |
| second_cta 場合により必須 | 2 番目のオプションの Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字（# はカウントしない）。 種別: string 注: title が設定されていない場合は必須。 例: #ShareAgain |
| second_cta_tweet 場合により必須 | 2 番目の CTA がクリックされたときに使用する Tweet のテキスト。 注: second_cta が設定されている場合は必須。 種別: string 例: I Heart @AdsAPI Again |
| title 場合により必須 | 画像の下、CTA の上に表示されるカードのタイトル。最大長: 23 文字。 種別: string 注: second_cta が設定されていない場合は必須。 例: Start a conversation |
| 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 |
| unlocked_image_media_key 任意 | インスタントアンロックのシナリオで使用する画像の media_key。 このフィールドは書き込み専用です。レスポンスでは、この画像の X の URL が返されます。 注: 画像はアカウントのメディアライブラリに存在している必要があります。 注: 画像の最小幅は 800px、幅:高さのアスペクト比は 5:2 が必要です。 種別: string 例: 3_883112887618682880 |
| thank_you_url 任意 | サンクステキストとともに表示される URL。 種別: 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
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| card_id 必須 | リクエストで操作する画像会話カードの参照。 種別: string 例: 4i0qg |
| first_cta 任意 | 1 つ目の選択肢の Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字（#はカウントしない）。 種別: string 例: #ShareNow |
| first_cta_tweet 任意 | 1 つ目の CTA がクリックされたときに使用される Tweet のテキスト。 種別: string 例: I Heart @AdsAPI |
| second_cta 任意 | 2 つ目の選択肢の Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字（#はカウントしない）。 注: title が設定されていない場合は必須。 種別: string 例: #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 のテキスト。 注: third_cta が設定されている場合は必須。 種別: string 例: I Heart @TwitterDev |
| fourth_cta 任意 | 4 つ目の選択肢の Call-To-Action (CTA) ハッシュタグ。最大長: 20 文字（#はカウントしない）。 種別: string 例: #ShareExtra |
| fourth_cta_tweet 任意 | 4 つ目の CTA がクリックされたときに使用される Tweet のテキスト。 注: fourth_cta が設定されている場合は必須。 種別: string 例: I Heart @TwitterDev Again |
| media_key 任意 | このカードで使用する画像のメディアキー。 注: 画像はアカウントの Media Library に存在している必要があります。 注: 最小画像幅は 800px、幅:高さのアスペクト比は 1.91:1 である必要があります。 種別: string 例: 3_1151345051104991073 |
| name 任意 | カードの名前。 種別: string 例: moon card |
| thank_you_text 任意 | CTA クリック後に表示されるテキスト。最大長: 23 文字。 種別: string 例: Thank you |
| thank_you_url 任意 | サンクス文と一緒に表示される URL。 種別: string 例: https://example.com/thankyou |
| title 任意 | 画像の下、CTA の上に表示されるカードのタイトル。最大長: 23 文字。 注: second_cta が設定されていない場合は必須。 種別: string 例: Start a conversation |
| unlocked_image_media_key 任意 | インスタントアンロック時に使用される画像の media_key。これは書き込み専用フィールドです。レスポンスでは、この画像の X の URL が返されます。 注: 画像はアカウントのメディアライブラリに存在している必要があります。 注: 最小画像幅は 800px、幅:高さのアスペクト比は 5:2 である必要があります。 種別: string 例: 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 リクエストで通常必須です。指定したアカウントは認証済みユーザーに紐づいている必要があります。 種別: string 例: 18ce54d4x5t |
| card_id 必須 | リクエストで操作する image conversation card への参照。 種別: string 例: 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
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| count 任意 | 各リクエストごとに取得を試行するレコード数を指定します。 種別: int 既定値: 20 最小/最大: 1/50 |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 種別: string 例: c-1 |
| media_type 任意 | 応答を指定したメディアタイプのみに絞り込みます。 種別: enum 取りうる値: GIF, IMAGE, VIDEO |
| q 任意 | name, title, file_name, description fields でリソースを絞り込むための任意のクエリ。 注: 大文字小文字を区別しない用語一致を行います。 種別: string 最小/最大長: 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
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| media_key 必須 | リクエストで操作するメディアライブラリ内のオブジェクトを参照するキー。 種別: string 例: 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
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| media_key 必須 | アップロード済みコンテンツの media_key。media_category を指定した場合、POST media/upload のレスポンスで media_key が返されます。 種別: string 例: 3_931236738554519552 |
| description 任意 | Post に含めると、動画の下に表示される説明。最大 200 文字。既定では Post 内に表示されません。動画の description を表示するには、POST accounts/:account_id/tweet エンドポイントで video_description パラメーターを使用してください。注: 動画にのみ使用できます。 種別: string 例: This is the description under the video. |
| file_name 任意 | メディアライブラリオブジェクトのファイル名。最大長 255。ファイル名は ads.x.com の Media Library UI の各メディアアセットのメディア詳細で確認できます。file_name が設定されていない場合は空になります。 種別: string 例: coffee.jpeg |
| name 任意 | メディアライブラリオブジェクトの名前。最大長 100。ads.x.com の Media Library UI で各メディアアセットのラベルとして表示されます。name が未設定の場合、ラベルは “Untitled” になります。 種別: string 例: Latte |
| poster_media_key 任意 | アップロードした画像の media_key を使用して、動画のポスター画像を指定します。未指定の場合は先頭フレームが使用されます。注: 動画にのみ使用できます。 種別: string 例: 3_890599134483242005 |
| title 任意 | Post に含めると、動画の下に表示されるタイトル（見出し）。最大 70 文字。既定では Post 内に表示されません。動画の title を表示するには、POST accounts/:account_id/tweet エンドポイントで video_title パラメーターを使用してください。注: 動画にのみ使用できます。 種別: string 例: Video title |
リクエスト例
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552
レスポンスの例
リソース 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: 16_844800354743074820 |
| description 任意 | Tweet 時に動画の下に表示される説明。最大長: 200文字。 これはデフォルトでは Tweet 内に表示されません。動画の description を表示するには、POST accounts/:account_id/tweet エンドポイントで video_description パラメーターを使用してください。 注: 動画にのみ使用できます。 Type: string Example: This is the description under the video. |
| file_name 任意 | メディアライブラリオブジェクトのファイル名。最大長: 255。 ファイル名は ads.x.com の Media Library UI の各メディアアセットのメディア詳細で確認できます。file_name が設定されていない場合は空になります。 Type: string Example: coffee.jpeg |
| name 任意 | メディアライブラリオブジェクトの名前。最大長: 100。 これは ads.x.com の Media Library UI において各メディアアセットの下に表示されるラベルです。name が設定されていない場合、ラベルは「Untitled」になります。 Type: string Example: Latte |
| poster_media_key 任意 | アップロード済み画像の media_key を使用して、動画のポスター画像を指定します。 注: 動画にのみ使用できます。 Type: string Example: 3_885003359340375465 |
| title 任意 | Tweet 時に動画の下に表示されるタイトル（見出し）。最大長: 70文字。 これはデフォルトでは Tweet 内に表示されません。動画の title を表示するには、POST accounts/:account_id/tweet エンドポイントで video_title パラメーターを使用してください。 注: 動画にのみ使用できます。 Type: string Example: Video title |
リクエスト例
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/16_844800354743074820?title=cat GIF&description=in space
レスポンスの例
リソース URL
https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象となるアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| media_key 必須 | リクエストで操作するメディアライブラリ内オブジェクトへの参照。 種別: string 例: 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
パラメータ
| Name | Description |
|---|---|
| account_id 必須 | 対象となるアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_ids 任意 | カンマ区切りの ID リストを指定して、目的の投票カードのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 57i77 |
| count 任意 | リクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow |
| q 任意 | name によるカードの絞り込みに用いる任意のクエリ。すべて取得する場合はこのパラメータを省略します。最大長: 80 文字。 注: 大文字小文字を区別しない前方一致で照合します。 Type: string Example: night |
| 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/cards/poll?card_ids=57i77
サンプルレスポンス
リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t |
| card_id 必須 | リクエストで操作対象となる投票カードの参照。 型: string 例: 57i8t |
| with_deleted 任意 | 削除済みの結果をレスポンスに含めます。 型: boolean 既定値: false 取りうる値: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i8t
レスポンスの例
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
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで基本的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| duration_in_minutes 必須 | 投票を公開しておく時間（分）。指定した duration_in_minutes を過ぎると投票は終了し、以後は投票できません。レスポンスの end_time に対応します。 注意: これはカードの作成と同時に開始され、Tweet に追加された時点では開始しません。 種別: int 最小/最大: 5、10080 |
| first_choice 必須 | 1つ目の投票選択肢。最大長: 25文字。 種別: string 例: One |
| name 必須 | カード名。 種別: string 例: poll card |
| second_choice 必須 | 2つ目の投票選択肢。最大長: 25文字。 種別: string 例: Two |
| fourth_choice 任意 | 4つ目の投票選択肢。最大長: 25文字。 注意: このパラメータを使用する場合は、1～3つ目の選択肢を設定する必要があります。 種別: string 例: Four |
| media_key 任意 | このカードで使用する、メディアライブラリ内の画像または動画の media_key。これは書き込み専用フィールドです。レスポンスでは、このメディアの X のURLが返されます。 注意: 画像または動画は当該アカウントのメディアライブラリ内にある必要があります。 注意: 画像の最小幅は800px、アスペクト比は幅:高さ = 1.91:1 が必要です。 |
| third_choice 任意 | 3つ目の投票選択肢。最大長: 25文字。 注意: このパラメータを使用する場合は、1および2つ目の選択肢を設定する必要があります。 種別: string 例: 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 必須 | 利用対象のアカウントを識別する ID。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t |
| card_id 必須 | リクエストで操作する投票カードへの参照。 型: string 例: 57i9t |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t
例: レスポンス
プリロールのCTA
GET accounts/:account_id/preroll_call_to_actions
現在のアカウント配下のラインアイテムに関連付けられたプレロールのCTA（Call-To-Action）の一部またはすべての詳細を取得します。リソース URL
https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| line_item_ids 任意 | 識別子のカンマ区切りリストを指定して、レスポンスを指定したラインアイテムに関連する preroll CTA のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 8v53k |
| count 任意 | リクエストごとに取得を試行するレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow |
| preroll_call_to_action_ids 任意 | 識別子のカンマ区切りリストを指定して、レスポンスを目的の preroll CTA のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 8f0 |
| 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/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 リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| preroll_call_to_action_id 必須 | リクエストで操作対象となるプレロールのコールトゥアクションへの参照。 種別: string 例: 8f0 |
| with_deleted 任意 | 削除済みの結果をレスポンスに含めます。 種別: boolean 既定値: false 取りうる値: 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（Call-to-Action）を更新します。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id
パラメータ
| Name | Description |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| preroll_call_to_action_id 必須 | リクエストで操作するプリー ロール CTA への参照。 Type: string Example: 8f0 |
| 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 |
リクエスト例
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 リクエストで一般的に必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| preroll_call_to_action_id 必須 | リクエストで操作するプルロールCTAへの参照。 種別: string 例: 8f0 |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0
レスポンスの例
予約投稿（Tweet）
GET accounts/:account_id/scheduled_tweets
現在のアカウントに関連付けられている一部またはすべてのScheduled Tweetsの詳細を取得します。リソース 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
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| scheduled_tweet_id 必須 | リクエストで操作対象となる Scheduled Tweet への参照。 種別: string 例: 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 で指定します。 注: Tweet は最大で 1 年先までしかスケジュールできません。 注: Tweet のスケジュールは分単位のみ対応し、秒は無視されます。 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
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| scheduled_tweet_id 必須 | このリクエストで操作する Scheduled Tweet を参照します。 Type: string Example: 870321875435442177 |
| card_uri 任意 | 利用可能な場合、いずれかの cards レスポンスの card_uri の値を使って、Tweet にカードを関連付けます。 注: 値なしでパラメーターのみを指定すると、未設定（削除）になります。 Type: string Example: card://875146925316386347 |
| media_keys 任意 | 識別子のカンマ区切りリストを指定して、Tweet にメディアを関連付けます。画像は最大4枚、アニメーション GIF は1件、または動画は1件まで含められます。 注: メディアアセットはアカウントの Media Library に存在している必要があります。 注: 値なしでパラメーターのみを指定すると、未設定（削除）になります。 Type: string Example: 13_1153584529292270722 |
| nullcast 任意 | nullcast（「Promoted-only」）の Tweet を作成するかどうか。 Type: boolean Possible values: true, false |
| scheduled_at 任意 | Tweet を公開（または配信開始）する時刻。ISO 8601 形式。 Type: string Example: 2017-12-31T23:59:59Z |
| text 任意 | ステータス更新の本文。 Type: string Example: just setting up my twttr |
| name 任意 | 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 リクエストで通常必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| scheduled_tweet_id 必須 | リクエストで操作する Scheduled Tweet への参照。 種別: string 例: 870321875435442177 |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776
応答例
Tweet のプレビュー
GET accounts/:account_id/tweet_previews
公開済み、予約済み、または下書きのTweetをプレビューします。- 単一のAPIリクエストで最大200件までの複数のTweetをプレビュー可能
- Tweetのレイアウトとスタイルを正確かつ最新の状態で再現
- 最新のすべてのフォーマットとカードタイプをサポート
- iframeを返します
リソース URL
https://ads-api.x.com/12/accounts/:account_id/tweet_previews
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | 利用するアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須です。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| tweet_ids 必須 | カンマ区切りの ID リスト。最大 200 個まで指定できます。 注: 各 ID は指定した tweet_type と一致している必要があります。たとえば、Scheduled Tweet の ID を渡して tweet_type=PUBLISHED を指定した場合、その ID のプレビューは返されません。 種別: long 例: 1122911801354510336,1102836745790316550 |
| tweet_type 必須 | 指定した tweet_ids に対応する Tweet の種別。 種別: enum 取りうる値: 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
パラメータ
| 名前 | 説明 |
|---|---|
| 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 任意 | 利用可能な Tweet 一覧からメンションと返信を除外するかどうか。 Type: boolean 既定値: false 取りうる値: true, false |
| name 任意 | name で Tweet を絞り込むための任意のクエリ。すべてを取得する場合はこのパラメータを省略します。最大長: 80 文字。 注: 大文字小文字を区別しない前方一致で照合します。 Type: string 例: dtc |
| timeline_type 任意 | nullcast（別名「Promoted-only」）の Tweet、オーガニック Tweet、またはその両方を返すかどうか。 Type: enum 既定値: NULLCAST 取りうる値: ALL, NULLCAST, ORGANIC |
| trim_user 任意 | Tweet レスポンスにおける user オブジェクトを除外するかどうか。有効にすると、返される user オブジェクトはその Tweet の投稿者のユーザー ID のみになります。 Type: boolean 既定値: false 取りうる値: true, false |
| tweet_ids 任意 | ID のカンマ区切りリスト。最大 200 個の ID を指定できます。 注: ID は指定した tweet_type に対応している必要があります。たとえば Scheduled Tweet の ID を渡す場合、その Tweet をレスポンスで返すには tweet_type を SCHEDULED にする必要があります。 Type: long 例: 1122911801354510336,1102836745790316550 |
| user_id 任意 | Tweet の絞り込み対象となるユーザーを指定します。未設定の場合、アカウント上の 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
アカウントのフルのプロモート可能ユーザー（デフォルト）またはas_user_id パラメーターで指定したユーザーとして Tweet を作成します。デフォルトのヌルキャストおよびオーガニックな Tweet の作成の両方をサポートします。ヌルキャストされた Tweet は公開タイムラインに表示されず、フォロワーにも配信されません。いずれの種類もキャンペーンで使用できます。
認証済みユーザーがこのアカウントの FULL プロモート可能ユーザーでない場合、GET accounts/:account_id/authenticated_user_access エンドポイントにリクエストして、このユーザーの代理で Tweet する権限があるか確認してください。TWEET_COMPOSER の権限がある場合は、このエンドポイントを使用して、FULL のプロモート可能ユーザーの代理でヌルキャストされた Tweet を作成できます。
メディアで upload.x.com エンドポイント を使用する場合、additional_owners パラメーターには、このエンドポイントに渡す as_user_id と同じ user_id の値を指定してください。
リソース URL
https://ads-api.x.com/12/accounts/:account_id/tweet
パラメータ
| Name | Description |
|---|---|
| account_id 必須 | 対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| as_user_id 必須 | あなたがTweetを代理投稿する広告主のユーザーID。広告主は ads.x.com を通じて、あなたのハンドル（1つまたは複数）に自社の広告アカウントへのアクセスを付与する必要があります。この権限により、広告主のものではなく自分のハンドルの OAuth トークンを使用して API を呼び出せます。 Type: long Example: 756201191646691328 |
| text 場合により必須 | ステータス更新のテキスト。media_keys が指定されていない場合は必須。 Type: string Example: hello, world |
| card_uri 任意 | 利用可能な場合、任意の cards レスポンスの card_uri 値を使用して Tweet にカードを関連付けます。 Type: string Example: card://853503245793641682 |
| conversation_settings 任意 | この Tweet に返信できるユーザーを選択します。メンションされたユーザーは常に返信できます。 注: このフィールドは POST リクエストのレスポンスでは返されませんが、GET リクエストでは返されます。 注: このパラメータは Ads API v8 以降でのみ有効です。 Type: enum Default: EVERYONE Possible values: EVERYONE, FOLLOWING, MENTIONED_USERS |
| media_keys 任意 | 識別子のカンマ区切りリストを指定して、Tweet にメディアを関連付けます。画像は最大4枚、アニメーション GIF は1つ、または動画は1本まで含められます。 Type: string Example: 13_1153584529292270722 |
| name 任意 | Tweet の名前。最大 80 文字。 Type: string Example: Tweet with name |
| nullcast 任意 | nullcast（「Promoted-only」）の Tweet を作成するかどうか。 注: オーガニック Tweet（nullcast=false）は認証済みユーザーに対してのみ作成できます。 Type: boolean Default: true Possible values: true, false |
| trim_user 任意 | Tweet レスポンスでユーザーオブジェクトを除外するかどうか。有効にすると、返されるユーザーオブジェクトは Tweet の作者のユーザーIDのみになります。 Type: boolean Default: false Possible values: true, false |
| tweet_mode 任意 | レスポンスを互換モードまたは拡張モードにするかどうか。詳細はこちらを参照。 Type: string Possible values: compat, extended |
| video_cta 任意 | 動画の CTA。 Type: enum Possible values: VISIT_SITE, WATCH_NOW |
| video_cta_value 任意 | 動画の対応する CTA の値。 Type: string Example: https://dev.x.com |
| video_description 任意 | 動画の下に表示される説明。最大 200 文字。 Type: string Example: Integrate with the X advertising platform |
| video_title 任意 | 動画の下に表示されるタイトル（見出し）。最大 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 リクエストで一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 種別: string 例: 18ce54d4x5t |
| tweet_id 必須 | このリクエストで操作対象となる Tweet への参照。 種別: long 例: 994747471329873920 |
| name 任意 | Tweet の名称。最大 80 文字。 種別: string 例: Tweet with name |
リクエスト例
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets/994747471329873920/name?name=new Tweet name
応答例
ビデオ会話カード
card_uri パラメータを POST accounts/:account_id/tweet、POST statuses/update、または POST accounts/:account_id/scheduled_tweets エンドポイントのいずれかで使用します。
GET accounts/:account_id/cards/video_conversation
現在のアカウントに関連付けられているビデオ会話カードの一部またはすべての詳細を取得します。リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation
パラメータ
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t |
| card_ids 任意 | カンマ区切りの識別子リストを指定して、対象の動画コンバセーションカードのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 型: string 例: 5a86h |
| count 任意 | 各リクエストで取得を試みるレコード数を指定します。 型: int デフォルト: 200 最小/最大: 1/1000 |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳しくは Pagination を参照してください。 型: string 例: 8x7v00oow |
| q 任意 | name でカードを絞り込むためのクエリ。すべて取得する場合はこのパラメータを省略します。最大長: 80 文字。 注: 大文字小文字を区別しない前方一致でマッチします。 型: string 例: night sky |
| sort_by 任意 | サポート対象の属性で昇順または降順に並べ替えます。詳しくは Sorting を参照してください。 型: string 例: created_at-asc |
| with_deleted 任意 | 削除済みの結果を含めます。 型: boolean デフォルト: false 取りうる値: true, false |
| with_total_count 任意 | レスポンス属性 total_count を含めます。 注: このパラメータと cursor は同時指定できません。 注: total_count を含むリクエストはレート制限が低く、現在は 15 分あたり 200 に設定されています。 型: 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
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| card_id 必須 | リクエストで操作する video conversation card への参照。 Type: string Example: 4i0ya |
| with_deleted 任意 | 削除済みの結果をレスポンスに含めます。 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
指定したアカウントに紐づく新しい Video Conversation Card を作成します。 エンドポイントへのメディア（画像など）のアップロードに関する有用な情報は、Uploading Mediaを参照してください。リソース URL
https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation
パラメータ
| 名前 | 概要 |
|---|---|
| アカウント_id必須 | レバレッジドアカウントの識別子。リソース内に表示されます’のパスに含まれ、一般的に GET accounts を除くすべての Advertiser API リクエストで必須のパラメータですGET accounts。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example:18ce54d4x5t |
| 最初_CTA必須 | 最初のオプション用のコールトゥアクション（CTA）ハッシュタグ。最大長：20文字（「#」は文字数に含めません）。 Type: string Example:#API |
| 最初の_CTA_Tweet必須 | 最初のCTAがクリックされたときに使用するTweetテキスト。 Type: string Example:広告 API |
| メディア_キー必須 | このカードで使用する動画のメディアキーです。注釈: 動画はそのアカウント内に存在している必要があります’sメディアライブラリー。注意: アスペクト比は16:9であることが必須です。 Type: string Example:13_1168079965037467209 |
| 名前必須項目 | カード名。 型: string 例:動画コンバセーションカード |
| ありがとう_あなた_テキスト必須 | CTA がクリックされた後に表示されるテキスト。最大長: 23 文字。 Type: string Example:構築する |
| タイトル必要な場合があります | カードのタイトル。動画の下、CTAの上に表示されます。最大長：23文字。型：string注釈: 必須（次の場合）second_ctaであるnot設定。例：開発者 |
| 秒_CTA場合によっては必須です | 2番目のオプション用のCall-To-Action（CTA）ハッシュタグ。最大長: 20文字（#は含めない）。型: string注: 次の条件で必須titleであるnot設定します。例:#もう一度シェア |
| 秒_CTA_Tweet場合によっては必須です | 2 つ目のCTAがクリックされたときに使用されるTweetテキスト。注釈: 次の場合は必須second_ctaが設定されている場合。 型: string 例:再び @AdsAPI に惚れ直した |
| ポスター_メディア_キー（任意） | このカードで使用するポスター画像のメディアキー。未指定の場合は、先頭のフレームが使用されます。注記: 動画はアカウントのメディアライブラリに存在している必要があります’sメディアライブラリ. 型: long 例:3_882726458191298561 |
| 3rd_CTA＊任意＊ | 3番目のオプション用のCall-To-Action（CTA）ハッシュタグ。最大文字数：20（#は含めない）。 Type: string Example:#もっとシェアしよう |
| 第三_CTA_Tweet場合によっては必須です | 3番目のCTAがクリックされたときに使用するTweetのテキスト。 Type: string注記: 次の場合に必須ですthird_ctaが設定されています。例:@TwitterDev が大好き |
| 4番目_CTA任意 | 4 番目のオプションのコールトゥアクション（CTA）用ハッシュタグ。最大長: 20 文字（# は含めない）。 Type: string Example:#ShareExtra |
| 4番目（fourth）_CTA_Tweet場合によっては必須です | 4番目のCTAがクリックされたときに使用するTweetのテキスト。 種別: string注: 次の場合に必須ですfourth_ctaが設定されています。例:また @TwitterDev が大好き |
| 感謝_お客様_URL任意 | 感謝メッセージと一緒に表示される URL。 型: string 例:https://example.com/thankyou |
| ロック解除済み_画像_メディア_キー任意 | Amedia_keyインスタントアンロックのシナリオで使用する画像。これは書き込み専用のフィールドです。レスポンスでは、この画像の X URL が API から返されます。注意: 画像はアカウント内に存在している必要があります’のメディアライブラリ内にある必要があります。種類: 文字列 例：3_883112887618682880 |
| ロック解除_動画_メディア_キー任意 | インスタントアンロックのシナリオで使用される、GET accounts/:account_id/media_library エンドポイントから取得した動画のID。GET accounts/:account_id/media_libraryインスタントアンロックのシナリオで使用されるエンドポイント。 型: 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
パラメータ
| 名称 | 概要 |
|---|---|
| アカウント_id必須 | レバレッジドアカウントの識別子。リソース内に表示されます’のパスに含まれ、一般的に GET accounts を除くすべての Advertiser API リクエストで必須のパラメータですGET accounts。指定されたアカウントは、認証済みユーザーに紐づいている必要があります。 Type: string Example:18ce54d4x5t |
| カード_id必須 | リクエストで操作する video conversation card への参照。 型: string 例:5a86h |
| 最初_CTA任意 | 最初のオプションのCall-To-Action（CTA）用ハッシュタグ。最大文字数：20（「#」は含めません）。 Type: string Example:#API |
| 最初_CTA_ツイート※任意 | 最初のCTAがクリックされた際に使用されるTweetテキスト。 型: string 例:広告 API |
| 秒_CTA任意 | 2番目のオプションのCall-To-Action（CTA）用ハッシュタグ。最大文字数: 「#」を含めず20文字。 型: string注記: 次の場合は必須titleであるnot設定されています。例:#もう一度共有 |
| 秒_CTA_Tweet任意 | 2番目のCTAがクリックされたときに使用するTweetのテキスト。注: 次の場合は必須second_ctaが設定されています。 Type: string Example:@AdsAPI がまた好きになった |
| 3番目_CTAオプション | 3 番目のオプションのコールトゥアクション（CTA）用ハッシュタグ。最大長：20文字（#は含めない）。 型：string 例:#もっとシェアしよう |
| 第3_CTA_Tweetオプション | 3番目のCTAがクリックされたときに使用するTweetのテキスト。 Type: string注意: 必須（該当する場合）third_ctaが設定されている場合。例:@TwitterDev が大好き |
| 第4_CTA任意（オプション） | 4 番目のオプションのコールトゥアクション（CTA）用ハッシュタグ。最大長: 20 文字（# は含めない）。 Type: string 例:#ShareExtra |
| 第4_CTA_Tweet任意 | 4 番目の CTA がクリックされたときに使用する Tweet テキスト。Type: string注記: 該当する場合は必須fourth_ctaが設定されている場合。例：また @TwitterDev が大好きに |
| メディア_キー任意（オプション） | このカードで使用する動画のメディアキー。注釈: 動画はアカウント内に存在している必要があります’sメディアライブラリ。注: アスペクト比は16:9であることが必須です。 Type: string Example:13_1168079965037467209 |
| 名前任意 | カード名。 型: string 例:developers card |
| ポスター_メディア_キー（任意） | このカードで使用するポスター画像のメディアキー。指定しない場合は、先頭フレームが使用されます。注意: 動画はアカウント内に存在している必要があります’sメディアライブラリ。 型: long 例:3_882726458191298561 |
| ありがとうございます_あなた_テキスト任意（オプション） | CTA をクリックした後に表示されるテキスト。最大文字数: 23。 Type: string Example:構築 |
| ありがとうございます_あなた_URL任意（オプション） | 感謝メッセージと共に表示されるURL。 Type: string Example:https://example.com/thankyou |
| タイトル任意 | カードのタイトル。動画の下、CTAの上に表示されます。最大長：23文字。 Type: string注記: 次の場合は必須second_ctaであるnot設定。例:会話を開始 |
| ロック解除済み_画像_メディア_キー任意 | Amedia_keyインスタントアンロックのシナリオで使用される画像。これは書き込み専用フィールドです。レスポンスでは、この画像の X URL が API により提供されます。注: 画像はアカウント内にある必要があります’メディアライブラリにある必要があります。 Type: string Example:3_883112887618682880 |
| ロック解除済み_動画_メディア_キー任意 | インスタントアンロックのシナリオで使用される GET accounts/:account_id/media_library エンドポイントから取得される動画の識別子GET accounts/:account_id/media_libraryインスタントアンロックのシナリオで使用するエンドポイント。 型: 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