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