素材 - X

概览

创意（Creatives）是指在广告系列中可以被推广的任何实体。Post 可以包含文本、图片、GIF、视频或卡片（Cards）。卡片可以包含图片或视频。图片、GIF 或视频类创意可通过 POST media/upload（一个仅支持图片的简单上传 endpoint），或通过 POST media/upload（分片）endpoints 进行上传。它们可以添加到卡片（Cards）：

POST accounts/:account_id/cards Tweets：
POST accounts/:account_id/tweets - 若要将卡片添加到 Tweets，请使用 card_uri 参数。 Scheduled Tweets：
POST accounts/:account_id/scheduled_tweets

有关卡片的更多详情，请参阅 Cards 页面。Promoted Video 页面提供了将视频与卡片或 Tweets 关联的详细信息。

卡片

X Ads API 支持多种可用于 Tweet 的卡片类型，之后可在广告系列中推广。注意：一旦作为 Tweet 发布，卡片详情将向公众可见，其中可能包含有关卡片所有者的信息。

图像

以下图像规范适用于 Cards 中使用的素材。图像大小必须不超过 3MB，且宽度至少为 800px。此外，我们支持以下宽高比：

Website：1:1 和 1.91:1
Image App Download：1:1 和 1.91:1
Poll：1.91:1
Image Conversation：1.91:1
Image Direct Message：1.91:1

我们支持以下图像格式：.bmp、.jpeg 和 .png。

视频

以下视频规范适用于 Cards 中使用的素材。我们支持以下宽高比：

视频网站：16:9 和 1:1
视频 App 下载：16:9 和 1:1
投票：16:9
视频会话：16:9
视频私信：16:9

推广视频

本文档简要概述了通过 X Ads API 上传并推广视频的流程。 X Ads API 支持在 Tweets 中使用推广视频，以及以下卡片类型：

首先，使用 POST media/upload (chunked) endpoint 上传视频。然后使用 media_id，通过 POST accounts/:account_id/videos endpoint 将该视频关联到广告账户。视频的 id（有时称为 media_key）将在后续请求中使用。该值是一个字符串：以一个整数开头，后接下划线，末尾为一个较长的数值。例如：13_875943225764098048。

推广视频（Tweet 中）

要创建一条 Tweet，请使用 POST accounts/:account_id/tweet endpoint，并提供该视频的 id。在此步骤中，你还可以提供视频标题、描述以及号召性用语（CTA）。这些值为面向用户的内容。

卡片中的推广视频

Video App Download 和 Video Conversation 卡片支持添加海报图片。使用 POST media/upload endpoint 上传用于这些卡片的图片。使用以下 endpoint 之一创建卡片：

使用视频的 id，以及可选的图片 media_id（作为海报图）。最后，使用 POST accounts/:account_id/tweet endpoint 创建 Tweet。通过 card_uri 参数将卡片附加到 Tweet。

常规信息

有关通过 API 上传视频的详细指南，请参阅视频上传指南。视频也可以作为前贴片素材进行投放。请参阅Video Views Pre-roll 目标指南了解详情。

（截至 2015-10-22）在上传用于推广内容的视频时，所有发送到 POST media/upload (chunked) endpoint 的 INIT 命令请求，其 media_category 参数必须设置为 amplify_video。使用此新参数可确保视频被异步预处理，并为推广内容做好准备。上传视频后，可使用 STATUS 命令检查异步处理是否完成。
目前允许的推广视频最长为 10 分钟，文件大小不超过 500MB。
上传视频应为 mp4 或 mov 格式。
上传视频通常处理较快，但处理时间可能因视频时长和文件大小而有所不同。
上传的海报图片应为 png 或 jpg 格式。对纵横比或尺寸没有硬性要求，但海报图片会调整以适配视频播放器。

使用指南

预定的 Tweet

介绍

Scheduled Tweets 允许广告主或用户创建一条 Tweet，并安排在未来某个时间发布。除了创建和管理这些 Tweets，API 还支持将其与某个 line item 关联，以便在 Tweet 上线后进行推广。这样，广告主就可以预先创建原生 Tweets，并在关键节点前提前规划活动素材。例如，将某条 Tweet 创意设置为在新品发布公告发布的同时立即上线。 Scheduled Tweets API 的完整功能集通过以下 endpoints 提供：

创建、修改和查看新近排期的 Tweets
将一条 Scheduled Tweet 关联到一个 line item
查询和管理现有的 scheduled Tweets
当一条 Scheduled Tweet 上线后，检索已上线 Tweet 的 id

API endpoint

与上述功能相关的全部 endpoint 如下：

由于计划 Tweets 与“实时”Tweets 为相互独立的实体，对这些 Tweets 的任何创建或编辑操作都会进行两套不同的验证。第一套验证规则在创建计划 Tweet 的步骤中执行，具体包括：

计划发布的 Tweet 创建：

验证已认证用户是否有权为指定的 @handle 创建自然（organic）Tweet。仅限推广（Promoted-Only）Tweet 的创建权限要求已认证用户为该账户的用户，并具备 Tweet composer permissions。
验证在计划的 scheduled_at 时间前后 15 分钟的时间窗口内，计划创建的 Tweet 不超过 30 条。出现 SCHEDULED_TWEET_LIMIT_EXCEEDED 错误消息表示在同一未来 15 分钟时间段内安排了过多的计划发布 Tweet。广告主需要删除现有的计划发布 Tweet，或将 scheduled_at 时间适当提前或推后。

预定的 Tweet 变为“上线”：

这些验证规则会在 scheduled_at 时间执行，与通过 API 创建常规 Tweet 时所适用的规则完全一致。比如，如果预定的 Tweet 同时包含图片和 GIF，则它不会上线，且 scheduled_status 将被设为 FAILED

工作流程

创建新的 Scheduled Tweet 可以使用 POST accounts/:account_id/scheduled_tweets endpoint 创建新的 Scheduled Tweet。该 endpoint 需要以下必填参数：scheduled_at 时间；如果 Tweet 中未包含媒体实体，还需提供 Tweet 的 text。此外，该 endpoint 提供了一些可选项，允许你通过 as_user_id 参数代表其他 @handle 创建计划 Tweet，并可添加卡片（card_uri）和媒体（media_ids）。注意，Tweet 中的实体类型必须一致，即只能是 Video、Gif 或 Image 之一。nullcast 参数用于控制该 Tweet 是否为“仅推广”Tweet。所有新创建的 Scheduled Tweet 默认均为“仅推广”（nullcast=true）。如果 nullcast=false，则会创建自然曝光的 Scheduled Tweet。成功创建 Scheduled Tweet 后，响应将包含一个 id 字段，表示该 Scheduled Tweet 本身的唯一标识符。除该字段外，还会返回一个名为 tweet_id 的字段。该字段初始为 null；当 Tweet 上线后，将填充为该“上线”Tweet 的 ID。

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

这将创建如下预定的 Tweet：

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

一旦此排程的 Tweet 上线，tweet_id 字段将填入该“上线”Tweet 的 ID。 查看排程的 Tweet 随后可使用 GET accounts/:account_id/tweet_previews endpoint，配合上一步中的排程 Tweet 的 id 生成该 Tweet 的预览。API 响应将包含一个可直接用于渲染排程 Tweet 预览的 iframe URL。相关的 CSS 和图像将由 X 直接提供。

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

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

上方展示了新建的已排程 Tweet 示例视图 将已排程 Tweet 与 line item 关联 虽然已排程 Tweet 可用于创建 Organic Tweet，我们也允许合作伙伴创建“仅推广”（nullcast=true）的 Tweet，这两者都可以与 line item 关联。为此，我们还提供了一个 POST accounts/:account_id/scheduled_promoted_tweets endpoint。该 endpoint 仅允许在一次 API 调用中将单个 Promoted Scheduled Tweet 关联到一个 line item。若要将多个已排程 Tweet 关联到同一 line item，需要进行多次 API 调用。请注意，无法修改现有的 Scheduled Promoted Tweet。

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

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

此 endpoint 仅在指定的 Scheduled Tweet 与某个 line item 之间创建关联。一旦 campaign/line item 的 flight 日期生效，该 line item 将自动开始投放相应的“live”Tweet。我们会在此步骤验证 Scheduled Tweet 处于 SCHEDULED 状态，并且该 Scheduled Tweet 符合给定的 objective，但不会进行其他校验。任何适用于 line item 和 Scheduled Tweet 的其余校验规则将在 Tweet 变为“live”时执行。为确保 campaign 投放不出现问题，建议将 Scheduled Tweet 的 scheduled_at 时间设置在 campaign/line item 的 flight 日期之前。例如，若 Scheduled Tweet 被设定为在 campaign 开始日期之后才上线（且仅有一个 Tweet 与单个 line item 关联），则 campaign 将处于 ACTIVE 状态，但由于 Scheduled Tweet 尚未上线，将没有可用于投放的创意。 Scheduled Tweet 管理 其余的 endpoints 允许 API 使用者管理其所有 Scheduled Tweets 和 Scheduled Promoted Tweets。这些 APIs 可用于返回所有 Scheduled Tweets 的列表（可按给定的 state 可选过滤），以及通过其 id 查询指定的 Scheduled Tweet。

计划的 Tweet 上线时会发生什么？

当某条计划的 Tweet 即将上线，也就是到达 scheduled_at 指定的时间点时，将进行以下更新：

会创建“上线”的 Tweet，但可能会有最长 1 秒的延迟
会将 tweet_id 添加到以下实体：
计划的 Tweet
推广的计划 Tweet
会创建一个新的推广 Tweet 实体

最佳实践

在创建或推广计划发布的 Tweet 时，建议遵循以下最佳实践：

在创建计划发布的 Tweet 时，确保该 Tweet 符合有效性要求（例如，一个 Tweet 只能包含 Image、Video 或 Gif 中的一种，不能组合使用）
确保广告投放时段（即 start_time 和 end_time）与该计划发布 Tweet 的 scheduled_at 时间一致
计划发布时间不应设置在未来一年（365 天）之后
目前不支持计划发布 Tweet 的预览（即在创建前预览计划发布的 Tweet）

媒体资料库

简介

Media Library endpoint 提供了管理 X Ads 账户中图像、GIF 和视频的功能。库中的媒体资产可用于 Tweets 和创建卡片，也可在多个creatives中重复使用，从而无需多次上传同一资产。

API 端点

POST media/upload 或 POST media/upload（分片）（上传媒体）
POST accounts/:account_id/media_library（将媒体添加到媒体库）

添加到库

将媒体添加到库需要两个步骤。首先，使用 POST media/upload endpoint 或 POST media/upload (chunked) 一组 endpoints 上传素材。（有关多段式上传流程的详细信息，请参阅 Chunked media upload 指南。）

twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media"

{
   "media_id":966947208837742592,
   "media_id_string":"966947208837742592",
   "size":74194,
   "expires_after_secs":86400,
   "image":{
      "image_type":"image/jpeg",
      "w":800,
      "h":418
   }
}

接下来，使用媒体的 id，通过 POST accounts/:account_id/media_library endpoint 将该媒体添加到广告账户的素材库。

twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_key=966947208837742592&name=Latte"

{
   "request":{
      "params":{
         "name":"Latte",
         "file_name":"latte.jpeg",
         "media_category":"TWEET_IMAGE",
         "account_id":"18ce54d4x5t",
         "media_key":966947208837742592
      }
   },
   "data":{
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

注意： 上传后立即发布包含图片、GIF 或视频的 Tweet 也会将这些媒体添加到媒体库。

请求参数

所有 Media Library 的 POST 请求都需要一个媒体标识符。该值会在上传步骤中返回。使用 media_id（如上述示例所示）时，还必须指定 media_category。类别共有四种可能的取值：AMPLIFY_VIDEO、TWEET_GIF、TWEET_IMAGE 和 TWEET_VIDEO。可选地，可以为 Media Library 中的对象设置 name 和 file_name 值。这些属性有助于用户在库中区分媒体变体。对于视频，还可以设置标题和描述。这些值用于作为 video_title 和 video_description 请求参数，与 POST accounts/:account_id/tweet endpoint 一起传递。在 Tweet 中，该文本显示在视频下方。

属性

Media Library 正式引入了 media_key 的概念。它是库中对象的唯一标识符。media_key 是如下格式的字符串值：13_875943225764098048。我们的所有卡片 endpoint 均完全支持这些值。此外，Media Library 的响应还包含以字符串表示的 media_id。对于当前尚不接受 media key 的资源，会包含该字段：Tweets、Tweet preview 和 Scheduled Tweets。我们正致力于在所有地方支持 media key。对于 GIF 和视频，会返回 aspect_ratio 属性。可用于为仅接受特定纵横比的卡片筛选可用媒体。 *这些 endpoint 支持 video_id 参数，该参数即为一个 media key。

使用说明

在本节中，下图将用于一条 Tweet，并用于创建一个网站卡片。

twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library/3_966947208837742592"

{
   "request":{
      "params":{
         "account_id":"18ce54d4x5t",
         "media_key":"3_966947208837742592"
      }
   },
   "data":{
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

Tweet 我们可以通过使用 media_keys 引用图片来创建该 Tweet。

twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=966947208837742592&as_user_id=756201191646691328&trim_user=true"

{
   "data":{
      "created_at":"Fri Feb 23 08:20:05 +0000 2018",
      "id":966950781302665218,
      "id_str":"966950781302665218",
      "text":"咖啡 https://t.co/T772Hx5GNT",
      "truncated":false,
      "entities":{
         "hashtags":[

         ],
         "symbols":[

         ],
         "user_mentions":[

         ],
         "urls":[

         ],
         "media":[
            {
               "id":966947208837742592,
               "id_str":"966947208837742592",
               "indices":[
                  7,
                  30
               ],
               "media_url":"http://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "media_url_https":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "url":"https://t.co/T772Hx5GNT",
               "display_url":"pic.x.com/T772Hx5GNT",
               "expanded_url":"https://x.com/apimctestface/status/966950781302665218/photo/1",
               "type":"photo",
               "sizes":{
                  "thumb":{
                     "w":150,
                     "h":150,
                     "resize":"crop"
                  },
                  "large":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "medium":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "small":{
                     "w":680,
                     "h":355,
                     "resize":"fit"
                  }
               }
            }
         ]
      },
      "source":"X Ads API 内部测试 App",
      "in_reply_to_status_id":null,
      "in_reply_to_status_id_str":null,
      "in_reply_to_user_id":null,
      "in_reply_to_user_id_str":null,
      "in_reply_to_screen_name":null,
      "user":{
         "id":756201191646691328,
         "id_str":"756201191646691328"
      },
      "geo":null,
      "coordinates":null,
      "place":null,
      "contributors":[
         2417045708
      ],
      "retweet_count":0,
      "favorite_count":0,
      "favorited":false,
      "retweeted":false,
      "possibly_sensitive":false,
      "scopes":{
         "followers":false
      },
      "lang":"en"
   },
   "request":{
      "params":{
         "as_user_id":756201191646691328,
         "text":"咖啡",
         "account_id":"18ce54d4x5t",
         "media_keys":[
            966947208837742592
         ],
         "trim_user":true
      }
   }
}

Website Card 我们所有的 cards endpoint 均支持 media keys。我们将通过引用该图片的 media_key 来创建 website card。

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

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

然后我们使用该卡片的 card_uri 将它与一条 Tweet 关联。

识别卡片类型

介绍

Cards 是可自定义的广告格式，使用媒体素材，并可与网站、App 或号召性用语（CTA）关联，以推动特定用户互动，例如发起 Direct Message。它们可以附加到 Tweets、Scheduled Tweets 或 Draft Tweets。在 Tweet 对象中可以通过两种方式引用 Cards：使用卡片的 card_uri 或其 preview_url。下面给出了各自的示例值。

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

注意：自 X Ads API 版本 3 起，对于新创建的卡片，cards 响应中仅生成并返回 card_uri。注意：自 X Ads API 版本 5 起，cards 响应中不再返回 preview_url。 Tweet 对象响应中引用的类型取决于 Tweet 的创建方式。换言之，如果使用 card_uri 请求参数创建 Tweet，响应中会出现该卡片 URI 值。相反，如果将 preview_url 作为 Tweet 文本的一部分包含在内，响应中会出现该预览 URL。

使用 card_uri 识别 Tweet

对于通过卡片的 URI 值创建的 Tweet，请在 card_uri 响应属性中查找该卡片的引用。下面的示例响应使用了 GET accounts/:account_id/tweets endpoint。

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

如果使用 Standard API，请在请求中加入 include_card_uri=true。无论调用哪个 endpoint，只有当该 Tweet 是通过 card URI 创建时，才会返回并呈现 card_uri 响应属性。对于已计划发布和草稿状态的 Tweet 对象，响应中将始终包含 card_uri 响应属性。

使用 preview_url 识别 Tweets

对于在 Tweet 文本中包含预览 URL 创建的 Tweets，可以在 entities[“urls”][i][“expanded_url”] 中找到该 URL（text 字段包含缩写的 t.co URL），其中 i 为数组索引（一个 Tweet 可包含多个 URL）。对于计划发送和草稿状态的 Tweet 对象，预览 URL 将始终出现在 text 字段中。

获取卡片

要获取特定卡片的更多信息，我们提供两个 endpoint：GET accounts/:account_id/cards/all 和 GET accounts/:account_id/cards/all/:card_id。前者可通过 card_uri 获取卡片，后者则可通过卡片的 id 获取。卡片的 id 位于 preview_url 的末尾。在上述示例中，id 为 68w3s。

识别媒资

介绍

媒体（图像、GIF 和视频）可以添加到 Tweets 和卡片中。此外，视频可用作片前广告素材，图像可以在 X Audience Platform 上推广。本节介绍如何在这些实体中定位媒体引用。媒体标识符分为两类：ID 和 key。下面给出了每种的示例值。

Media ID	Media key
1029825579531807971	13_1029825579531807971

Media key 由 ID 加上一个数字前缀和下划线组成。

图像

下表展示了各与图像相关的资源在其响应中当前可用的标识符类型及相应的属性名称。

资源	标识符	属性
Image cards	无
Tweet	二者皆有	`entities["media"]["id_str"]` `entities["media"]["media_key"]`
Scheduled Tweet	二者皆有	`media_ids` 和 `media_keys`
Draft Tweet	二者皆有	`media_ids` 和 `media_keys`
Account Media	无
Media Library	二者皆有	`media_id` 和 `media_key`

Image cards 和 Account Media 的图像不包含对任何媒体标识符的引用。Tweets 仅包含媒体 ID。Scheduled 和 Draft Tweets 同时包含媒体 ID 和媒体 key。Media Library 也同时返回二者。对于 Tweets，entities[“media”] 数组中对象的 id 和 id_str 字段对应媒体 ID。若一条 Tweet 包含多张图片，对各媒体实体的引用只能在 extended_entities[“media”] 中找到。除标识符引用外，通常还需要获取图像的 URL。

资源	属性	格式
Image cards	`image`	.jpg
Tweet*	`entities["media"][0]["media_url"]` 或 `extended_entities["media"][i]["media_url"]`	.jpg
Scheduled Tweet	无
Draft Tweet	无
Account Media	`media_url`	.jpg
Media Library	`media_url`	.jpg

该 URL 的位置取决于 Tweet 含有单张还是多张图片。

所有 Image cards 都包含一个图像响应属性，其中包含 X 图像 URL。（对于 image app download cards，名称为 wide_app_image。）对于 Tweets，media URL 的位置取决于媒体类型以及所使用的 endpoint。若 Tweet 仅包含一张图片，可在 entities[“media”][0][“media_url”] 中找到该 URL。这对 X Ads API 和 Standard API 均适用。而当 Tweet 含有多张图片时，URL 只能在 extended_entities[“media”][i][“media_url”] 中找到，该位置仅在 Standard API 中可用。

视频

下表列出了各视频相关资源的响应中当前可用的标识符类型及其对应的属性名称。

资源	标识符	属性
视频卡片	可能为任一	`video_content_id`
视频投票卡片	无
Tweet	两者皆有	`entities["media"]["id_str"]` `entities["media"]["media_key"]`
计划发布的 Tweet	两者皆有	`media_ids` 和 `media_keys`
Tweet 草稿	两者皆有	`media_ids` 和 `media_keys`
账号媒体	Media key	`video_id`
媒体库	两者皆有	`media_id` 和 `media_key`

尽管视频卡片（带视频的投票卡片除外）包含 video_content_id 响应属性，但返回值的类型并不一致。有时是 media ID；在另一些情况下是 media key。如何获取视频 URL 的信息如下所示。

资源	属性	格式
视频卡片	`video_url` 和 `video_hls_url`	.vmap .m3u8
带视频的 Tweet	`extended_entities["media"][i]["video_info"]["variants"][j]["url"]`	.mp4
计划发布的 Tweet	无
Tweet 草稿	无
账号媒体	无
媒体库	`media_url`	.mp4

视频卡片包含 video_url 和 video_hls_url 响应属性，分别对应 .vmap 和 .m3u8 URL。

媒体库

有时需要获取媒体资产的更多信息。以视频卡片为例，可能需要获取 mp4 URL 而不是 vmap URL。这些信息可在媒体库中获得。有关可用信息的详细说明，请参阅我们的媒体库指南。广告账户的 FULL promotable user 所属的大多数资产都可在该库中找到，但也有一些例外。 获取媒体 如上所述，图片卡片不包含对 media ID 或 media key 的引用。因此，无法通过媒体库获取其资产。Account Media 图片也同样如此。视频卡片要求在创建之前，视频资产已存在于媒体库（或其前身 Videos 资源）中。因此，这些资产始终可以在媒体库中检索。Account Media 的 PREROLL 资产也同样如此。最后，Tweet 中的媒体始终保证存在于媒体库中。下表总结了哪些资产可在媒体库中检索，并考虑了资源响应是否包含可用于查找的标识符。

资源	在媒体库中
图片卡片	否
视频卡片	是*
Tweets（任意媒体）**	是
已排程的 Tweets	是
草稿 Tweets	是
Account media 图片	否
Account media 视频（`PREROLL`）	是

适用于 video_content_id 为 media key 的卡片。当该值为 media ID 时，资产仍存在于媒体库中，但检索它需要在其前面追加一个数字前缀和下划线。 ** Tweets 仅返回 media ID。虽然资产保证存在于媒体库中，但获取它需要在其前面追加一个数字前缀和下划线。

与 Account Media 的交互 有两种情况会将添加到媒体库中的媒体资产自动添加到 Account Media 资源中。

当 AMPLIFY_VIDEO 资产被添加到媒体库时，会自动作为 PREROLL 创意类型添加为 Account Media 资产。
当具有特定尺寸的图片（参见我们的枚举页面中的“Creative Types”）被添加到媒体库时，它们会自动添加为 Account Media 资产。创意类型（例如，INTERSTITIAL）取决于图片尺寸。

Tweets

简介

X Ads API 支持三种类型的 Tweet：已发布、预定发布和草稿。

Nullcasted Tweets

Tweets 可以是 nullcasted（又称“Promoted-only”）或自然（organic）。已发布的 nullcasted Tweets 虽然为公开内容，但不会出现在用户的公开时间线上。相比之下，自然 Tweets 会投放给用户的关注者，并会出现在用户的公开时间线上。 创建 Tweets 三个用于创建 Tweet 的 endpoint 均支持一个布尔型的 nullcast 参数，使 API 用户可以选择创建 nullcasted 或自然 Tweets。nullcasted Tweets 可以由该用户创建，或由任何获准以该用户名义创建 Tweets 的人创建。自然 Tweets 只能由完全可推广用户创建。 更新 Tweets 已计划发布（scheduled）和草稿（draft）的 Tweets 可以更新其 nullcast 属性。对于计划发布的 Tweets，可在 Tweet 的 scheduled_at 时间之前进行编辑。草稿 Tweets 可以无限期编辑。但一旦发布，就无法在 nullcasted 与自然之间相互更改。

推广 Tweets

只有已发布和已排期的 Tweets 可以被推广。它们可以是 nullcasted 或 organic，均无限制。广告主可以推广自己的 Tweets，或在获得许可的情况下推广其他用户的 Tweets。（参见：Promoting another user’s Tweets 了解更多信息。）在单个广告系列中可以推广多个 Tweets。同样，单条 Tweet 也可以在一个或多个广告系列中进行推广。要推广已发布的 Tweets，请使用 POST accounts/:account_id/promoted_tweets endpoint。这会将已发布的 Tweets 与一个 line item 关联。要推广已排期的 Tweets，请使用 POST accounts/:account_id/scheduled_promoted_tweets endpoint。

Tweet ID

已发布、已排期和草稿的 Tweet ID 均为数值，即 64 位无符号整数。例如，以下已发布 Tweet 的 ID 为 1166476031668015104。当已发布或已排期的 Tweet 被推广时，会创建相应的推广 Tweet 实体。此类实体拥有各自的 ID，采用字母数字组合，并以 base-36 编码表示。例如，推广上述已发布的 Tweet——即将其关联到 line item 6c62d——会返回以下 API 响应。

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

除了在创建请求中传入的 Tweet ID 和 line item ID 之外，响应还包含一个值为 3qw1q6 的 id 字段，即推广 Tweet 的 ID。

轮播图

介绍

X Ads API 支持创建和检索视频轮播与图片轮播。轮播是一种卡片类型，可包含 2 到 6 个媒体素材。轮播卡片可以将用户引导至网站，或鼓励他们安装移动 App。有关轮播、其优势、最佳实践和常见问题的更多信息，请参阅我们的 Carousel Ads on X 页面。与其他卡片类型一样，轮播可用于 Tweets，且这些 Tweets 随后可以被推广。工作流程与您已经熟悉的一致：

上传媒体
创建卡片
创建 Tweet
推广 Tweet

唯一的区别在于卡片的创建方式。其他卡片创建请求接受 query 参数，而轮播卡片创建请求仅接受 JSON 的 POST 请求正文。

Endpoints

X Ads API 支持创建和获取轮播。要创建任意类型的轮播，请使用 POST accounts/:account_id/cards endpoint。要获取轮播，请使用 GET accounts/:account_id/cards endpoint。

JSON POST Body

轮播由两个组件构成。第一个用于指定要使用的媒体资源，第二个用于指定网站或 App 的相关信息。具体而言，轮播卡片按以下顺序由这些组件组成：

一个 SWIPEABLE_MEDIA 组件，接受一个媒体键数组
以下组件中的一个：
一个 DETAILS 组件，用于指定网站信息
一个 BUTTON 组件，用于指定 App 信息

SWIPEABLE_MEDIA 组件必须包含一个 media_keys 数组，你可以在其中指定 2 到 6 个图片或视频。传入媒体键的顺序决定了它们的渲染顺序。

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

提醒：你可以通过向 GET accounts/:account_id/media_library endpoint 发起请求来获取媒体密钥。第二个组件对象的构成取决于你希望将用户引导至网站，还是鼓励他们安装 App。下表汇总了这两种选项。（注意：所列出的所有键均为必填。）

	网站	App
指定组件类型	`"type": "DETAILS"`	`"type": "BUTTON"`
标题/标签	`"title": "X"`	`"label": { "type": "ENUM", "value": "INSTALL" }`
目标	`"destination": { "type": "WEBSITE", "url": "https://www.x.com" }`	`"destination": { "type": "APP", ... }`

将上述内容组合在一起，下面展示了一个网站轮播的 JSON POST 请求体示例。

{
  "name": "网站轮播图",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "DETAILS",
      "title": "X"
      "destination": {
        "type": "WEBSITE",
        "url": "https://www.x.com"
      }
    }
  ]
}

BUTTON 组件中的 App 目标对象需要提供国家/地区代码以及至少一个 App 标识符，并可选地包含深度链接。有关这些字段的说明，请参阅参考文档。综合以上要求，下面给出一个应用轮播的 JSON POST 请求体示例。

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

示例

本节演示如何创建视频网站轮播卡片，以及如何在 Tweet 中使用它。如上所述，工作流程与您已熟悉的相同：上传媒体、创建卡片、创建 Tweet。唯一的不同在于卡片的创建方式。媒体首先，上传新的媒体资产或使用现有资产。有关如何上传新的媒体资产并将其添加到媒体库的详细信息，请参阅我们的媒体库指南。当您的媒体资产已在媒体库中后，使用 GET accounts/:account_id/media_library endpoint 获取它们。使用 media_type 请求参数将结果限定为特定媒体类型。

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

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

创建轮播 使用 POST accounts/:account_id/cards endpoint 创建轮播。使用上一个请求返回的 media key。请注意，传入 media key 的顺序将决定其呈现顺序。

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

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

请注意，与其他卡片相同，轮播卡片的响应包含一个 card_uri，在创建 Tweet 时将会用到。 Tweet 使用 POST accounts/:account_id/tweet endpoint 创建 Tweet。请使用上一个请求返回的 card_uri。（为便于阅读，响应已截断。）

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

{
  "data": {
    "created_at": "Wed Nov 11 07:58:27 +0000 2020",
    "id": 1326434098324385792,
    "id_str": "1326434098324385792",
    "text": "滑动",
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "X Ads API 内部测试 App",
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
      "id": 756201191646691300,
      "id_str": "756201191646691328",
      ...
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": [
      2417045708
    ],
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "possibly_sensitive": false,
    "scopes": {
      "followers": false
    },
    "lang": "en",
  },
  "request": {
    "params": {
      "text": "滑动"
      "as_user_id": 756201191646691300,
      "card_uri": "card://1326432421105995776",
      "account_id": "18ce54d4x5t"
    }
  }
}

Tweet 预览 使用 GET accounts/:account_id/tweet_previews endpoint 查看您的 Tweet。

创意 metadata 标记

介绍

本指南面向创意合作伙伴、代理机构及创意开发者，旨在为 X 活动中使用的素材添加标签，以更好地评估单个素材的价值与表现。 注意： 媒体素材只能由其创作者（合作伙伴或开发者）进行标记。若媒体素材的使用者并非其创作者，请不要实施元数据标记。 Creative Metadata Tagging 可为由创意合作伙伴创建的图片和视频提供归因，不论素材上传至 X 的何处，或由何方上传。为在创意素材与创意合作伙伴之间建立关联，我们使用 XMP 标准。

标记创意素材

下表展示了当前每个与图像相关的资源响应中可用的标识符类型及其对应的属性名称。为创意素材打标签需要使用标记工具。推荐使用 ExifTool，这是一款跨平台的 Perl 库及其命令行应用程序，可用于读取、写入和编辑元信息。查看所有支持的文件类型。请按照提供的ExifTool 安装说明进行操作。也可通过 Homebrew 提供的软件包，使用适用于 macOS 和 Linux 的 exiftool 安装命令进一步简化安装。在命令行输入 exiftool -ver，查看返回的版本号以确认工具已正确安装。在 ExifTool 文档中了解更多 ExifTool 命令参数。创意合作伙伴可在新的或现有的创意素材上，将其 X app_id 写入 contributor XMP 标签和 date 标签，以添加 metadata 标签。上传媒体时，创意素材将遵循现有的大小限制。 注意： X 使用 contributor XMP 标签可确保 metadata 仅用于记录在 X 上的广告投放活动相关取值。 exiftool -contributor="<YOUR APP ID>" -creative_file.jpg exiftool -date="<date>" -creative_file.jpg app_id 可在 Developer Portal 的 Projects & Apps 下找到。示例：16489123 以下示例将 app_id 添加为 contributor 标签，并将 date 添加为 date 标签到一张图像中：

app_id:858382169

日期:2022-03-13

creative_file: eiffel_tower.jpg

exiftool -contributor=858382169 eiffel_tower.jpg

   1 个图像文件已更新

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

  1 个图像文件已更新

验证你的图像是否已正确标注： exiftool -xmp:all -G1 <filename> 示例： exiftool -xmp:all -G1 eiffel_tower.jpg

[XMP]        XMP 工具包             ：Image::ExifTool 12.30

[XMP]        贡献者            ：858382169

[XMP]        日期                   : 2022:03:13

有问题？

如果您想确认标记与归因是否已成功，请将已打标的示例素材发送至 adsapi-program@x.com，供 X 代表审核。

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 请求所需的参数。指定的账户必须与已认证用户关联。类型: string 示例: `18ce54d4x5t`
account_media_ids 可选	通过指定以逗号分隔的标识符列表，将响应限定为所需的账户媒体。最多可提供 200 个 ID。类型: string 示例: `3wpx`
count 可选	指定每个请求尝试检索的记录数量。类型: int 默认值: `200` 最小值/最大值: `1`/`1000`
creative_types 可选	将响应限定为与指定创意类型匹配的账户媒体。可通过逗号分隔的枚举值指定多个创意类型。类型: enum 可选值: `BANNER`, `BANNER_TABLET`, `INTERSTITIAL`, `INTERSTITIAL_LANDSCAPE`, `INTERSTITIAL_LANDSCAPE_TABLET`, `INTERSTITIAL_TABLET`, `MEDIUM_RECTANGLE`, `PREROLL`, `VAST_PREROLL`
cursor 可选	指定用于获取下一页结果的游标。参见 Pagination 了解更多信息。类型: string 示例: `8x7v00oow`
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/account_media?account_media_ids=3wpx

示例响应

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

检索与当前账户关联的特定媒体对象。

资源 URL

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

参数

名称	描述
account_id 必填	该广告账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
account_media_id 必填	在请求中所操作的账户媒资的引用。 Type: string Example: `2pnfd`
with_deleted 可选	是否在请求结果中包含已删除项。 Type: boolean Default: `false` Possible values: `true`, `false`

示例请求

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

示例响应内容

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

删除当前账号下的指定账号媒体对象。

资源 URL

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

参数

名称	描述
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

示例响应

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

Cards

注意：要将卡片与 Tweet 关联，请在 POST accounts/:account_id/tweet、POST statuses/update、POST accounts/:account_id/scheduled_tweets 或 POST accounts/:account_id/draft_tweets 这些 endpoint 中使用 card_uri 参数。检索与当前账户关联的部分或全部卡片的详细信息。注意：仅返回使用 POST accounts/:account_id/cards 这个 endpoint 创建的卡片。通过其他 endpoint 创建的卡片不会返回。

资源 URL

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

参数

名称	描述
account_id 必填	被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型: string 示例: `18ce54d4x5t`
card_types 可选	通过指定以逗号分隔的枚举值列表，将响应限定为所需的卡片类型。类型: 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 可选	通过指定以逗号分隔的标识符列表，将响应限定为所需的卡片。最多可提供 200 个卡片 ID。类型: string 示例: `1044294149527166979,1044301099031658496`
card_uris 可选	通过指定以逗号分隔的标识符列表，将响应限定为所需的卡片。最多可提供 200 个卡片 URI 值。类型: string 示例: `card://1044294149527166979,card://1044301099031658496`
count 可选	指定每个请求尝试检索的记录数。类型: int 默认值: `100` 最小值/最大值: `1`/`200`
cursor 可选	指定用于获取下一页结果的游标。参见分页了解更多信息。类型: string 示例: `8x7v00oow`
include_legacy_cards 可选	在响应中包含旧版网站和 App 卡片。旧版卡片的资源 URL 格式为：accounts/:account_id/cards/:card_type。更多背景请参阅此开发者论坛帖子。类型: boolean 默认值: `false` 可能的取值: `true`, `false`
q 可选	可选的 query（查询），用于按 `name` 限定卡片。省略此参数以检索全部。最大长度：80 个字符。注意：执行不区分大小写的前缀匹配。类型: string 示例: `dtc`
sort_by 可选	按受支持的属性进行升序或降序排序。参见排序了解更多信息。类型: string 示例: `created_at-asc`
with_deleted 可选	在请求中包含已删除的结果。类型: boolean 默认值: `false` 可能的取值: `true`, `false`

示例请求

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

示例响应

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

获取与当前账户关联的单个卡片的详细信息。

资源 URL

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

参数

名称	说明
account_id 必填	被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已验证的用户关联。 Type: string Example: `18ce54d4x5t`
card_id 必填	卡片的 id。 Type: string Example: `1044294149527166979`
with_deleted 可选	在请求中包含已删除的结果。 Type: boolean Default: `false` Possible values: `true`, `false`

示例请求

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

示例响应

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

POST accounts/:account_id/cards

创建一个与指定账户关联的新卡片。创建卡片的请求仅接受 JSON 格式的 POST 请求体。Content-Type 必须设置为 application/json。有关详细用法示例，请参阅我们的 Carousels 指南。

资源 URL

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

参数

JSON POST 正文必须包含卡片的 name 和一个 components 数组。components 以对象形式表示，用于描述卡片面向广告主的属性。下面的示例展示了负载的一般结构（但包含无效信息）。

{
  "name": "某个名称",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}

下面是关于组件的补充信息。

Name	Description
account_id required	被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求都需要的参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
name required	卡片名称。最大长度：80 个字符。 Type: string Example: `component based card`
components sometimes required	用于创建卡片的组件描述。更多信息见下文。不可与 `slides` 同时指定。注意：组件的顺序很重要。 Type: array of objects
slides sometimes required	使用此二维数组创建 Multi-Destination Carousel。将每张卡片描述为组件的分组。每个幻灯片都应完整表示一张卡片。不可与 `components` 同时指定。注意：每个幻灯片的顺序很重要。 Type: array of array

组件

每个组件都必须包含一个 type 字段，用于确定对象的架构。X Ads API 支持以下组件类型，分为媒体类组件和描述类组件。

媒体：
MEDIA：单个视频或图像
SWIPEABLE_MEDIA：2–6 个视频或图像
描述：
DETAILS
BUTTON

每个组件都有一组必填字段（除 type 键之外）。如下表所示。

组件 `type`	字段	值类型
`MEDIA`	`media_key`	string
`SWIPEABLE_MEDIA`	`media_keys`	array of strings
`DETAILS`	`title` `destination`	string object
`BUTTON`	`label` `destination`	object object

下面是在 components 数组中的一个 BUTTON 组件示例（有意省略 name 键）。（省略号表示需要补充更多信息的部分。）

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

指定组件对象的顺序决定了它们自上而下的渲染顺序。卡片必须由一个媒体类组件与一个 DETAILS 或 BUTTON 组件组合创建。基于描述的组件会在媒体下方渲染，并带有关联的目标，可为 URL 或移动 App。 Label 标签定义按钮上显示的文本，因此仅适用于 BUTTON 组件。Label 对象包含两个必填键：type 和 value。type 必须设为 ENUM，value 可为以下之一：BOOK、CONNECT、INSTALL、OPEN、ORDER、PLAY 或 SHOP。在前一个示例的基础上，以下展示了 BUTTON 组件中的 label 对象。

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

目标目标是广告主希望将用户引导至的去向。它在 DETAILS 或 BUTTON 组件中始终为必填项。目标类型包括两种：WEBSITE 或 APP。注意：网站目标仅可与 DETAILS 组件搭配使用，应用目标仅可与 BUTTON 组件搭配使用。 网站目标

名称	描述
type 必填	目标类型，用于确定其模式（schema）。类型：枚举可选值：`WEBSITE`
url 必填	要将用户重定向至的网站 URL。类型：字符串示例：`https://devcommunity.x.com/c/advertiser-api`

应用目标

名称	描述
type 必填	目标类型，用于确定其模式（schema）。类型：枚举可选值：`APP`
country_code 必填	应用售卖所在国家/地区的 ISO 3166-1 alpha-2 两字母代码。类型：字符串示例：`US`
googleplay_app_id 有时必填	Google Play 应用包名。注意：以下至少一项为必填：`ios_app_store_identifier` 或 `googleplay_app_id`。类型：字符串示例：`com.twitter.android`
ios_app_store_identifier 有时必填	iOS App Store 标识符。注意：以下至少一项为必填：`ios_app_store_identifier` 或 `googleplay_app_id`。类型：字符串示例：`333903271`
googleplay_deep_link 可选	指向所推广 Android 应用的深度链接。注意：仅在已提供 `googleplay_app_id` 时可用。类型：字符串
ios_deep_link 可选	指向所推广 iOS 应用的深度链接。注意：仅在已提供 `ios_app_store_identifier` 时可用。类型：字符串

示例请求

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

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

示例响应

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

更新与当前账户关联的指定资源。卡片编辑请求仅接受 JSON 格式的 POST 请求体。Content-Type 必须设置为 application/json。

资源 URL

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

参数

JSON POST 请求体必须包含要更新的参数。请求会将各字段替换为载荷中指定的参数。组件以对象表示，描述卡片对广告主可见的属性。以下示例展示了载荷的总体结构（其中包含无法实际使用的信息）。

{
  "name": "某个名称",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}

有关 POST accounts/:account_id/cards 中组件与幻灯片的补充信息。

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 Carousels。将每张卡片描述为组件的分组。每个幻灯片都应完整表示一张卡片。不可与 `components` 同时指定。注意：每个幻灯片的顺序很重要。Type: array of array

示例请求

此示例会同时更新名称，并从上述示例的 components 字段中删除一个 media_keys。 PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

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

示例响应

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

删除当前帐号名下的指定卡片。

资源 URL

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

参数

名称	说明
account_id 必填	被使用账户的标识符。出现在资源路径中，且通常为除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
card_id 必填	要删除的卡片 id。类型：string 示例：`1044294149527166979`

示例请求

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

示例响应

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

获取卡片

检索与当前账户关联的多个卡片，按 card_uri 指定。

资源 URL

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

参数

名称	说明
account_id 必填	被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
card_uris 必填	通过提供以逗号分隔的标识符列表，将响应限定为所需的卡片。最多可提供 200 个卡片 URI 值。类型：string 示例：`card://1044294149527166979,card://1044301099031658496`
with_deleted 可选	在请求中包含已删除的结果。类型：boolean 默认值：`false` 可能的取值：`true`、`false`

示例请求

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

示例响应

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

通过 card_id 获取与当前账户关联的特定卡片。

资源 URL

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

参数

名称	说明
account_id 必填	使用中的账户标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已通过身份验证的用户关联。类型: string 示例: `18ce54d4x5t`
card_id 必填	请求中所操作的卡片引用。类型: string 示例: `508pf`
with_deleted 可选	是否在请求中包含已删除的结果。类型: boolean 默认值: `false` 可能的取值: `true`, `false`

示例请求

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

示例响应

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

Tweet 草稿

GET accounts/:account_id/draft_tweets

检索与当前账户关联的部分或全部草稿 Tweet 的详细信息。

资源 URL

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

参数

名称	说明
account_id 必填	目标账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 Type: string 示例：`18ce54d4x5t`
count 可选	指定每个请求尝试检索的记录数量。 Type: int 默认值：`100` 最小/最大值：`1`、`200`
cursor 可选	指定用于获取下一页结果的游标。更多信息参见 Pagination。 Type: string 示例：`c-jh1g0ryb`
user_id 可选	指定要为其检索草稿 Tweet 的用户。未设置时，默认为账户上的 `FULL` 可推广用户。 Type: string 示例：`756201191646691328`

示例请求

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

示例响应

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

获取与当前账户关联的特定 Tweet 草稿。

资源 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

示例响应

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

POST accounts/:account_id/draft_tweets

为该账户的完整可投放用户（默认）或在 as_user_id 参数中指定的用户创建一个 Draft Tweet。

资源 URL

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

参数

名称	说明
account_id 必填	被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
as_user_id 必填	代表其发布该 Tweet 的广告主的用户 ID。广告主必须通过 ads.x.com 授予你的 handle（或多个 handle）对其广告账户的访问权限。此权限允许你使用自己 handle 的 OAuth 令牌而非广告主的令牌来调用 API。 Type: string Example: `756201191646691328`
text 有时必填	状态更新的文本。如果未指定 `media_keys`，则为必填。 Type: string Example: `Just setting up my X.`
card_uri 可选	使用任一卡片响应中的 `card_uri` 值（如果有）将卡片与该 Tweet 关联。 Type: string Example: `card://960880280705392541`
media_keys 可选	通过指定逗号分隔的标识符列表，将媒体与该 Tweet 关联。最多可包含 4 张图片、1 个动态 GIF 或 1 个视频。注意：媒体资源必须位于该账户的 Media Library 中。 Type: string Example: `13_1153584529292270722`
nullcast 可选	是否创建 nullcast（或“仅推广”）的 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/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.

示例响应

{
  "request": {
    "params": {
      "text": "刚开始设置我的 X。",
      "as_user_id": "756201191646691328"
    }
  },
  "data": {
    "name": null,
    "text": "刚开始设置我的 X。",
    "user_id": "756201191646691328",
    "id": "994747471329873920",
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:14:13Z",
    "media_keys": []
  }
}

更新当前账户名下指定的草稿 Tweet。

资源 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 张图片、1 个动画 GIF 或 1 个视频。注意：媒体资源必须位于该账户的 Media Library 中。注意：可通过仅提供该参数但不赋值来取消设置（移除）。类型：string 示例：`13_1153584529292270722`
nullcast 可选	是否创建一个 nullcast（“仅推广”）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

示例响应

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

永久删除当前账户中的指定 Draft Tweet。注意：我们强烈建议在使用其 metadata 创建了 Tweet 或 Scheduled Tweet 后删除草稿。注意：这是硬删除。因此，无法恢复已删除的 Draft Tweets。

资源 URL

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

参数

名称	说明
account_id 必填	杠杆账户的标识符。出现在资源路径中，且通常是所有 Advertiser API 请求的必需参数，但不包括 GET accounts。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
draft_tweet_id 必填	在此请求中所操作的 Draft Tweet 的引用。 Type: string Example: `994787835663155200`

示例请求

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

示例响应

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

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

在移动设备上预览草稿 Tweet。成功的请求会向已认证用户已登录的每台设备发送通知。点击通知会打开时间线，用户可查看并与该草稿 Tweet 交互，用于测试自动播放、音量、全屏、视频网站卡片停驻等行为。注意：设备端预览仅对接收该通知的用户可见。注意：通知仅会发送到 X 官方 App。

资源 URL

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

参数

名称	说明
account_id 必填	已杠杆账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已通过身份验证的用户关联。Type: string Example: `18ce54d4x5t`
draft_tweet_id 必填	请求中所操作的 Draft Tweet 的引用。Type: string Example: `996132315829948416`

示例请求

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

示例响应

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "draft_tweet_id": "996132315829948416"
    }
  },
  "message": "请在 X App 中查看 @apimctestface 的通知，以预览你的 Tweet。"
}

Image Conversation Cards

注意：要将卡片与 Tweet 关联，请在以下任一 endpoint 中使用 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

参数

名称	说明
account_id 必填	已授权使用的广告账户标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
card_ids 可选	通过指定以逗号分隔的标识符列表，将响应限定为所需的图像会话卡片。最多可提供 200 个 ID。类型：string 示例：`59woh`
count 可选	指定每个请求尝试检索的记录数。类型：int 默认值：`200` 最小值/最大值：`1`/`1000`
cursor 可选	指定用于获取下一页结果的游标。参见分页了解更多信息。类型：string 示例：`8x7v00oow`
q 可选	按 `name` 限定卡片的可选 query（查询）。省略此参数以检索全部。最大长度：80 个字符。注意：执行不区分大小写的前缀匹配。类型：string 示例：`night`
sort_by 可选	按受支持的属性进行升序或降序排序。参见排序了解更多信息。类型：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

示例响应

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_ids": [
        "59woh"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "图片对话卡片",
      "first_cta": "#月亮",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "感谢",
      "id": "59woh",
      "first_cta_tweet": "群星",
      "media_key": "3_957113581522141184",
      "created_at": "2018-01-27T04:58:42Z",
      "image_display_width": "1280",
      "card_uri": "card://923498485702009837",
      "title": "满月"
      "updated_at": "2018-01-27T04:58:42Z",
      "deleted": false,
      "card_type": "IMAGE_CONVERSATION"
    }
  ]
}

检索与当前账户关联的特定图片对话卡片。

资源 URL

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

参数

名称	说明
account_id 必填	盈利用账户的标识符。该值出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
card_id 必填	你在该请求中所操作的图片会话卡片的引用。 Type: string Example: `59woh`
with_deleted 可选	在请求中包含已删除的结果。 Type: boolean Default: `false` Possible values: `true`, `false`

示例请求

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

示例响应

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_id": "59woh",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "图片对话卡",
    "first_cta": "#月亮",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "感谢",
    "id": "59woh",
    "first_cta_tweet": "群星",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "满月"
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  }
}

POST accounts/:account_id/cards/image_conversation

为指定账户创建新的图像会话卡片。有关向我们的 endpoint 上传图像的实用信息，请参阅上传媒体。

资源 URL

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

参数

名称	描述
account_id 必填	已授权账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已通过验证的用户关联。 Type: string Example: `18ce54d4x5t`
first_cta 必填	第一项的号召性用语（CTA）话题标签。最大长度：20 个字符（不计入“#”）。 Type: string Example: `#ShareNow`
first_cta_tweet 必填	点击第一个 CTA 时要使用的 Tweet 文本。 Type: string Example: `I Heart @AdsAPI`
media_key 必填	此卡片所用图像的 media key。注意：图像必须位于该账户的 Media Library 中。注意：图像最小宽度为 800px，且宽高比需为 1.91:1。 Type: string Example: `3_1151345051104991073`
name 必填	卡片名称。 Type: string Example: `image conversation card`
thank_you_text 必填	点击 CTA 后显示的文本。最大长度：23 个字符。 Type: string Example: `Thank you`
second_cta 有时必填	第二项的号召性用语（CTA）话题标签。最大长度：20 个字符（不计入“#”）。 Type: string 注意：当未设置 `title` 时必填。 Example: `#ShareAgain`
second_cta_tweet 有时必填	点击第二个 CTA 时要使用的 Tweet 文本。注意：当已设置 `second_cta` 时必填。 Type: string Example: `I Heart @AdsAPI Again`
title 有时必填	卡片标题，显示在图像下方、CTA 上方。最大长度：23 个字符。 Type: string 注意：当未设置 `second_cta` 时必填。 Example: `Start a conversation`
third_cta 可选	第三项的号召性用语（CTA）话题标签。最大长度：20 个字符（不计入“#”）。 Type: string Example: `#ShareMore`
third_cta_tweet 有时必填	点击第三个 CTA 时要使用的 Tweet 文本。 Type: string 注意：当已设置 `third_cta` 时必填。 Example: `I Heart @TwitterDev`
fourth_cta 可选	第四项的号召性用语（CTA）话题标签。最大长度：20 个字符（不计入“#”）。 Type: string Example: `#ShareExtra`
fourth_cta_tweet 有时必填	点击第四个 CTA 时要使用的 Tweet 文本。 Type: string 注意：当已设置 `fourth_cta` 时必填。 Example: `I Heart @TwitterDev Again`
unlocked_image_media_key 可选	在即时解锁场景中要使用的图像 `media_key`。这是一个仅写字段。在响应中，API 将为此图像提供一个 X URL。注意：图像必须位于该账户的 Media Library 中。注意：图像最小宽度为 800px，且宽高比需为 5:2。 Type: string Example: `3_883112887618682880`
thank_you_url 可选	与致谢文本一起显示的 URL。 Type: string Example: `https://example.com/thankyou`

示例请求

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

示例响应

{
  "data": {
    "name": "图片互动卡片",
    "first_cta": "#月亮",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "谢谢",
    "id": "59woh",
    "first_cta_tweet": "群星",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "满月",
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "name": "图片互动卡片",
      "first_cta": "#月亮",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "谢谢",
      "media_key": "3_957113581522141184",
      "account_id": "18ce54d4x5t",
      "first_cta_tweet": "群星",
      "image_display_width": "1280",
      "title": "满月"
      "card_type": "IMAGE_CONVERSATION"
    }
  }
}

更新当前账户所属的指定图片会话卡片。有关向我们的 endpoint 上传图片的实用信息，请参阅上传媒体。

资源 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 可选	第一个选项的号召性用语（CTA）话题标签。最大长度：20 个字符（不包含 #）。类型：string 示例：`#ShareNow`
first_cta_tweet 可选	点击第一个 CTA 时使用的 Tweet 文本。类型：string 示例：`I Heart @AdsAPI`
second_cta 可选	第二个选项的号召性用语（CTA）话题标签。最大长度：20 个字符（不包含 #）。类型：string 注意：当未设置 `title` 时必填。示例：`#ShareAgain`
second_cta_tweet 可选	点击第二个 CTA 时使用的 Tweet 文本。注意：如果已设置 `second_cta`，则必填。类型：string 示例：`I Heart @AdsAPI Again`
third_cta 可选	第三个选项的号召性用语（CTA）话题标签。最大长度：20 个字符（不包含 #）。类型：string 示例：`#ShareMore`
third_cta_tweet 可选	点击第三个 CTA 时使用的 Tweet 文本。类型：string 注意：如果已设置 `third_cta`，则必填。示例：`I Heart @TwitterDev`
fourth_cta 可选	第四个选项的号召性用语（CTA）话题标签。最大长度：20 个字符（不包含 #）。类型：string 示例：`#ShareExtra`
fourth_cta_tweet 可选	点击第四个 CTA 时使用的 Tweet 文本。类型：string 注意：如果已设置 `fourth_cta`，则必填。示例：`I Heart @TwitterDev Again`
media_key 可选	此卡片中要使用的图片的 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 个字符。类型：string 注意：当未设置 `second_cta` 时必填。示例：`Start a conversation`
unlocked_image_media_key 可选	在即时解锁场景中将使用的图片的 `media_key`。这是一个仅写字段。在响应中，API 会为此图片提供一个 X URL。注意：图片必须位于该账户的媒体库中。注意：图片最小宽度为 800px，且宽高比为 5:2。类型：string 示例：`3_883112887618682880`

示例请求

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

示例响应

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

永久删除当前账户所属的指定图片会话卡片。注意：这是硬删除，删除后无法恢复或找回该卡片。

资源 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

示例响应

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

媒体库

GET accounts/:account_id/media_library

获取与当前账户关联的部分或全部媒体库对象的详细信息。

资源 URL

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

参数

名称	说明
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 可选	可选的 query（查询），用于按 `name`、`title`、`file_name` 和 `description` fields 限定资源。注意：执行不区分大小写的词项匹配。类型：string 最小/最大长度：`1`/`255`

示例请求

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

示例响应

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "count": 1
    }
  },
  "data": [
    {
      "tweeted": true,
      "name": null,
      "file_name": "coffee https://t.co/4tcPU9XUon",
      "media_url": "https://pbs.twimg.com/media/DJvnJf_UEAAXnzC.jpg",
      "media_category": "TWEET_IMAGE",
      "media_key": "3_908573900237180928",
      "created_at": "2017-09-15T06:11:12Z",
      "media_status": "TRANSCODE_COMPLETED",
      "media_type": "IMAGE",
      "updated_at": "2017-11-16T06:00:01Z",
      "deleted": false
    }
  ],
  "next_cursor": "c-1"
}

获取与当前账号关联的指定媒体库对象。

资源 URL

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

参数

名称	说明
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

示例响应

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "13_909110614026444802"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 39973,
    "name": null,
    "file_name": "buildings https://t.co/xFdzrHM5QG",
    "description": null,
    "media_url": "https://video.twimg.com/amplify_video/909110614026444802/vid/1280x720/mfahmfkKVjjk1nGm.mp4",
    "media_category": "AMPLIFY_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/909110614026444802/img/QZUNoaiCia0UFNrw.jpg",
    "poster_media_key": "3_909110614026444802",
    "media_key": "13_909110614026444802",
    "created_at": "2017-09-16T17:43:55Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "buildings",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-09-27T13:04:00Z",
    "deleted": false
  }
}

将媒体对象关联到当前账户。更多详情请参阅我们的 Media Library 指南。注意：将媒体类别为 AMPLIFY_VIDEO 的视频添加到 Media Library 后，它会自动作为 PREROLL 类型的 account_media 资源可用。

资源 URL

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

参数

名称	描述
account_id 必填	已使用的账号标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账号必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
media_key 必填	已上传内容的 `media_key`。当指定了 `media_category` 时，POST media/upload 的响应会返回一个 `media_key`。类型：string 示例：`3_931236738554519552`
description 可选	在发布为 Tweet 时显示在视频下方的描述。最大长度：200 个字符。默认情况下不会在 Tweet 中呈现。要显示视频的 `description`，请在 POST accounts/:account_id/tweet endpoint 中使用 `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 可选	在发布为 Tweet 时显示在视频下方的标题（headline）。最大长度：70 个字符。默认情况下不会在 Tweet 中呈现。要显示视频的 `title`，请在 POST accounts/:account_id/tweet endpoint 中使用 `video_title` 参数。注意：仅可用于视频。类型：string 示例：`Video title`

示例请求

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

示例响应

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "3_931236738554519552"
    }
  },
  "data": {
    "tweeted": false,
    "name": null,
    "file_name": null,
    "media_url": "https://pbs.twimg.com/media/DOxq4TtV4AAlvh_.jpg",
    "media_category": "TWEET_IMAGE",
    "media_key": "3_931236738554519552",
    "created_at": "2017-11-16T19:05:14Z",
    "media_status": "TRANSCODE_COMPLETED",
    "media_type": "IMAGE",
    "updated_at": "2017-11-16T19:05:23Z",
    "deleted": false
  }
}

更新当前账号下的指定媒体库对象。

资源 URL

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

参数

名称	说明
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 endpoint 中使用 `video_description` 参数。注意：仅适用于视频。 Type: string Example: `This is the description under the video.`
file_name 可选	媒体库对象的文件名。最大长度：255。该文件名可在 ads.x.com 的 Media Library 界面的每个媒体资产详情中查看。未设置 `file_name` 时，此字段为空。 Type: string Example: `coffee.jpeg`
name 可选	媒体库对象的名称。最大长度：100。这是 ads.x.com 的 Media Library 界面中每个媒体资产下方显示的标签。未设置 `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 endpoint 中使用 `video_title` 参数。注意：仅适用于视频。 Type: string Example: `Video title`

示例请求

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

示例响应

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "16_844800354743074820",
      "title": "猫咪 GIF",
      "description": "在太空中"
    }
  },
  "data": {
    "tweeted": true,
    "duration": null,
    "name": null,
    "file_name": null,
    "description": "在太空中",
    "media_url": "https://video.twimg.com/tweet_video/C7lVclqVwAQqTCZ.mp4",
    "media_category": "TWEET_GIF",
    "poster_media_url": "https://pbs.twimg.com/tweet_video_thumb/C7lVclqVwAQqTCZ.jpg",
    "poster_media_key": "3_844800354743074820",
    "media_key": "16_844800354743074820",
    "created_at": "2017-10-20T09:51:54Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "猫咪 GIF",
    "media_type": "GIF",
    "aspect_ratio": "125:79",
    "updated_at": "2017-10-23T06:37:56Z",
    "deleted": false
  }
}

删除当前账户的指定媒体库对象。

资源 URL

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

参数

名称	说明
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

示例响应

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "7_860318603387600896"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 14330,
    "name": "mountains-on-ads.x.com",
    "file_name": "mountains.mp4",
    "description": "",
    "media_url": "https://video.twimg.com/ext_tw_video/860318603387600896/pu/vid/1280x720/xI3DbvWKxdvICsFW.mp4",
    "media_category": "TWEET_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/media/C_B3bTRVYAAFBFt.jpg",
    "poster_media_key": "3_860318839740915712",
    "media_key": "7_860318603387600896",
    "created_at": "2017-05-05T02:21:53Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "已上传至 ads.x.com",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-05-05T02:26:58Z",
    "deleted": true
  }
}

投票卡

GET accounts/:account_id/cards/poll

获取与当前账户关联的部分或全部投票卡片的详细信息。

资源 URL

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

参数

名称	说明
account_id 必填	被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求必需的参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
card_ids 可选	通过指定以逗号分隔的标识符列表，仅返回所需的投票卡。最多可提供 200 个 ID。类型：string 示例：`57i77`
count 可选	指定每个请求尝试检索的记录数。类型：int 默认值：`200` 最小/最大：`1`/`1000`
cursor 可选	指定用于获取下一页结果的游标。更多信息请参见 Pagination。类型：string 示例：`8x7v00oow`
q 可选	可选的 query（查询），用于按 `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/poll?card_ids=57i77

示例响应

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

获取与当前账户关联的特定投票卡。

资源 URL

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

参数

名称	说明
account_id 必填	杠杆账户的标识符。该值出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所必需的参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
card_id 必填	本次请求所操作的投票卡片引用。 Type: string Example: `57i8t`
with_deleted 可选	是否在请求中包含已删除的结果。 Type: boolean Default: `false` Possible values: `true`, `false`

示例请求

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

示例响应

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_id": "57i8t",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "纯文本投票",
    "start_time": "2018-01-09T05:03:05Z",
    "first_choice": "上午",
    "second_choice": "晚上",
    "end_time": "2018-01-11T05:03:05Z",
    "id": "57i8t",
    "created_at": "2018-01-09T05:03:05Z",
    "duration_in_minutes": "2880",
    "card_uri": "card://950593749658189824",
    "updated_at": "2018-01-09T05:03:05Z",
    "deleted": false,
    "card_type": "TEXT_POLLS"
  }
}

POST accounts/:account_id/cards/poll

创建与指定账户关联的新投票卡片。此 endpoint 支持创建带有图片、视频或无媒体的投票卡片。包含媒体的投票称为 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 必填	第一项投票选项。最大长度：25 个字符。类型：string 示例：`One`
name 必填	卡片名称。类型：string 示例：`poll card`
second_choice 必填	第二项投票选项。最大长度：25 个字符。类型：string 示例：`Two`
fourth_choice 可选	第四项投票选项。最大长度：25 个字符。注意：使用此参数时必须同时设置第一、第二和第三选项。类型：string 示例：`Four`
media_key 可选	在此卡片中使用的媒体库图片或视频的 `media_key`。这是一个仅写字段。在响应中，API 将提供该媒体的 X URL。注意：图片或视频必须位于该账户的媒体库中。注意：图像最小宽度为 800px，且需要 1.91:1 的宽高比。
third_choice 可选	第三项投票选项。最大长度：25 个字符。注意：使用此参数时必须同时设置第一和第二选项。类型：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

示例响应

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

永久删除当前账号下指定的投票卡片。注意：这是硬删除，因此无法恢复或找回已删除的卡片。

资源 URL

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

参数

名称	说明
account_id 必填	目标账户的标识符。出现在资源路径中，通常是所有 Advertiser API 请求（除 GET accounts 外）的必填参数。指定的账户必须与已通过身份验证的用户关联。类型：string 示例：`18ce54d4x5t`
card_id 必填	在该请求中所操作的投票卡片的标识引用。类型：string 示例：`57i9t`

示例请求

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

示例响应

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

片头前置号召性操作

GET accounts/:account_id/preroll_call_to_actions

检索当前账号下各个投放单（line item）关联的部分或全部前贴片号召性用语（CTA）的详细信息。

资源 URL

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

参数

名称	说明
account_id 必填	被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
line_item_ids 可选	通过指定以逗号分隔的标识符列表，将响应限定为与指定 line item 关联的 preroll CTA。最多可提供 200 个 ID。类型：string 示例：`8v53k`
count 可选	指定每个请求尝试检索的记录数。类型：int 默认值：`200` 最小值/最大值：`1`/`1000`
cursor 可选	指定用于获取下一页结果的游标。更多信息参见 Pagination。类型：string 示例：`8x7v00oow`
preroll_call_to_action_ids 可选	通过指定以逗号分隔的标识符列表，将响应限定为所需的 preroll CTA。最多可提供 200 个 ID。类型：string 示例：`8f0`
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/preroll_call_to_actions?line_item_ids=8v53k

示例响应

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

检索与此账户关联的特定号召性用语（CTA）。

资源 URL

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

参数

名称	说明
account_id 必填	目标账户的标识符。该参数出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填项。指定的账户必须与已通过身份验证的用户关联。类型：string 示例：`18ce54d4x5t`
preroll_call_to_action_id 必填	本次请求所操作的预播呼吁性行动（preroll call to action）的引用。类型：string 示例：`8f0`
with_deleted 可选	是否在请求中包含已删除的结果。类型：boolean 默认值：`false` 可选值：`true`、`false`

示例请求

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

示例响应

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

POST accounts/:account_id/preroll_call_to_actions

为 PREROLL_VIEWS 明细项设置可选的号召性用语（CTA）。

资源 URL

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

参数

名称	描述
account_id 必填	已授权账户的标识符。出现在资源路径中，通常是除GET accounts外所有 Advertiser API 请求的必需参数。指定账户必须与已验证用户关联。类型：string 示例：`18ce54d4x5t`
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`
line_item_id 必填	请求中所操作的广告单元（line item）的引用。类型：string 示例：`8v53k`

示例请求

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

示例响应

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

更新 PREROLL_VIEWS 广告项的可选号召性用语（CTA）。

资源 URL

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

参数

名称	描述
account_id 必填	被使用账户的标识符。该值出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
preroll_call_to_action_id 必填	本次请求中所操作的 preroll CTA 的引用。类型：string 示例：`8f0`
call_to_action 可选	广告中显示按钮的 CTA 文本。类型：enum 可能的取值：`GO_TO`、`SEE_MORE`、`SHOP`、`VISIT_SITE`、`WATCH_NOW`
call_to_action_url 可选	点击 CTA 按钮后重定向用户的 URL。类型：string 示例：`https://www.x.com`

示例请求

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

示例响应

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

删除当前账户下指定的前贴片号召性用语（CTA）。

资源 URL

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

参数

名称	说明
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

示例响应

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

计划 Tweets

GET accounts/:account_id/scheduled_tweets

获取与当前账户关联的部分或全部已计划 Tweet 的详细信息。

资源 URL

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

参数

名称	说明
account_id 必填	目标账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。Type: string 示例：`18ce54d4x5t`
count 可选	指定每个请求尝试检索的记录数。Type: int 默认值：`100` 最小值/最大值：`1`/`200`
cursor 可选	指定用于获取下一页结果的游标。更多信息参见分页。Type: string 示例：`c-j3cn6n40`
user_id 可选	指定要检索预定发布 Tweets 的用户。未设置时默认为账户上的 `FULL` 可推广用户。Type: long 示例：`756201191646691328`

示例请求

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

示例响应

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name": "测试名称",
      "completed_at": "2017-06-18T22:00:05Z",
      "text": "你想要到达的地方",
      "user_id": "756201191646691328",
      "scheduled_status": "SUCCESS",
      "id": "875828692081037312",
      "nullcast": true,
      "created_at": "2017-06-16T21:33:27Z",
      "scheduled_at": "2017-06-18T22:00:00Z",
      "card_uri": null,
      "updated_at": "2017-06-19T18:02:20Z",
      "tweet_id": "876560168963645440",
      "media_keys": []
    }
  ],
  "next_cursor": "c-j41uw400"
}

检索与当前账户关联的特定预定发布的 Tweet。

资源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

示例响应

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

POST accounts/:account_id/scheduled_tweets

为该账号的完整可推广用户（默认）或在 as_user_id 参数中指定的用户创建一个 Scheduled Tweet。

资源 URL

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

参数

名称	说明
account_id 必填	被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
scheduled_at 必填	Tweet 计划发布（上线）的时间，采用 ISO 8601 格式。注意：Tweet 最多只能安排到未来一年内。注意：Tweet 仅应按分钟粒度进行排程；秒数将被忽略。类型：string 示例：`2017-12-31T23:59:00Z`
as_user_id 必填	代为发布 Tweet 的广告主的用户 ID。广告主必须通过 ads.x.com 授予你的账号句柄（或多个句柄）访问其广告账户的权限。此权限允许你使用自己句柄的 OAuth 令牌调用 API，而非广告主的令牌。类型：long 示例：`756201191646691328`
text 有时必填	状态更新的文本。若未指定 `media_keys`，则必填。类型：string 示例：`just setting up my twttr`
card_uri 可选	使用任意 cards 响应中的 `card_uri` 值（如可用）将卡片与该 Tweet 关联。类型：string 示例：`card://855591459410511943`
media_keys 可选	通过指定以逗号分隔的标识符列表，将媒体与 Tweet 关联。最多可包含 4 张图片、1 个动图 GIF 或 1 个视频。注意：媒体资产必须位于该账户的 Media Library 中。类型：string 示例：`13_1153584529292270722`
nullcast 可选	是否创建 nullcast（或“仅推广”）Tweet。类型：boolean 默认值：`true` 可能的取值：`true`，`false`
name 可选	计划 Tweet 的名称。最大长度：80 个字符。类型：string 示例：`Tweet with name`

示例请求

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

示例响应

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

更新当前账号中指定的已排程 Tweet。

资源 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 可选	使用任意卡片响应中的 `card_uri` 值（如有）将卡片关联到该 Tweet。注意：如需取消设置（移除），仅传递该参数但不提供值。 Type: string Example: `card://875146925316386347`
media_keys 可选	通过指定以逗号分隔的标识符列表将媒体关联到该 Tweet。最多可包含 4 张图片、1 个动画 GIF，或 1 段视频。注意：媒体资产必须位于该账户的 Media Library 中。注意：如需取消设置（移除），仅传递该参数但不提供值。 Type: string Example: `13_1153584529292270722`
nullcast 可选	是否创建 nullcast（“仅推广”）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

示例响应

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

永久删除当前账号下的指定已排程 Tweet。注意：这是硬删除，因此无法恢复已删除的已排程 Tweet。

资源 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

示例响应

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

Tweet 预览

GET accounts/:account_id/tweet_previews

预览已发布、已排期或草稿状态的 Tweet。

支持在单次 API 请求中预览多条 Tweet（最多 200 条）
精确、及时地还原 Tweet 的布局与样式
支持所有最新格式和卡片类型
返回一个 iframe

资源 URL

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

参数

名称	描述
account_id 必填	被使用账户的标识符。该值出现在资源路径中，通常是除GET accounts外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
tweet_ids 必填	以逗号分隔的标识符列表。最多可提供 200 个 ID。注意：这些 ID 应与指定的 `tweet_type` 相匹配。例如，如果传入的是 Scheduled Tweet 的 ID 且指定了 `tweet_type=PUBLISHED`，将不会返回该 ID 的预览。 Type: long Example: `1122911801354510336,1102836745790316550`
tweet_type 必填	与所提供 `tweet_ids` 对应的 Tweet 类型。 Type: enum Possible values: `DRAFT`, `PUBLISHED`, `SCHEDULED`

示例请求

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

示例响应

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

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 可选	指定用于获取下一页结果的游标。更多信息请参阅分页。 Type: string 示例：`AAAAAFhLRpQLNF-sGBSgAA`
include_mentions_and_replies 可选	是否从可用 Tweets 列表中过滤掉提及和回复。 Type: boolean 默认值：`false` 可能的取值：`true`、`false`
name 可选	通过 `name` 限定 Tweets 的可选 query（查询）。省略此参数以检索全部。最大长度：80 个字符。注意：执行不区分大小写的前缀匹配。 Type: string 示例：`dtc`
timeline_type 可选	返回 nullcast（又称“仅推广”）Tweets、自然 Tweets，或两者皆可。 Type: enum 默认值：`NULLCAST` 可能的取值：`ALL`、`NULLCAST`、`ORGANIC`
trim_user 可选	是否在 Tweet 响应中排除用户对象。启用时，用户对象中仅返回该 Tweet 作者的用户 ID。 Type: boolean 默认值：`false` 可能的取值：`true`、`false`
tweet_ids 可选	逗号分隔的标识符列表。最多可提供 200 个 ID。注意：这些 ID 应与指定的 `tweet_type` 相对应。例如，如果传入的是已排程的 Tweet 的 ID，则 `tweet_type` 必须为 `SCHEDULED`，该 Tweet 才会在响应中返回。 Type: long 示例：`1122911801354510336,1102836745790316550`
user_id 可选	指定要限定 Tweets 的用户。未设置时，默认使用账户中的 `FULL` 可推广用户。 Type: long 示例：`756201191646691328`

示例请求

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

示例响应

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

POST accounts/:account_id/tweet

为该账户的完整可推广用户（默认）或在 as_user_id 参数中指定的用户创建一条 Tweet。支持创建屏蔽投放（nullcast，默认）和自然 Tweet。屏蔽投放的 Tweets 不会出现在公共时间线，也不会分发给关注者。两种类型均可用于广告活动。如果经过身份验证的用户并非此账户的 FULL 级可推广用户，请通过调用 GET accounts/:account_id/authenticated_user_access endpoint 确认其是否有权代表该用户发布 Tweet。权限值 TWEET_COMPOSER 表示该用户可以使用此 endpoint 代表 FULL 级可推广用户创建屏蔽投放的 Tweets。当为媒体使用 upload.x.com endpoint 时，请为 additional_owners 参数传入与本 endpoint 中 as_user_id 相同的 user_id 值。

资源 URL

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

参数

名称	描述
account_id 必填	被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求所需的参数。指定的账户必须与已认证用户关联。 Type: string Example: `18ce54d4x5t`
as_user_id 必填	代表其发布此 Tweet 的广告主的用户 ID。广告主必须通过 ads.x.com 授予你的账号（或多个账号）对其广告账户的访问权限。此权限允许你使用自己账号的 OAuth 令牌而不是广告主的令牌来调用 API。 Type: long Example: `756201191646691328`
text 有时必填	状态更新的文本。如果未指定 `media_keys`，则必填。 Type: string Example: `hello, world`
card_uri 可选	使用任一卡片响应中的 `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 张图片、1 个动图 GIF 或 1 个视频。 Type: string Example: `13_1153584529292270722`
name 可选	Tweet 的名称。最大长度：80 个字符。 Type: string Example: `Tweet with name`
nullcast 可选	是否创建 nullcast（“仅推广”）的 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

示例响应

{
  "data": {
    "created_at": "Sat Jun 24 05:08:30 +0000 2017",
    "id": 878479925472251906,
    "id_str": "878479925472251906",
    "text": "你好，世界",
    "name": null,
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "<a href='"https://ads-api.x.com"' rel='"nofollow"'>X Ads API 内部测试应用</a>",
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
      "id": 756201191646691328,
      "id_str": "756201191646691328"
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": null,
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "你好，世界",
      "trim_user": true,
      "as_user_id": 756201191646691328,
      "account_id": "18ce54d4x5t"
    }
  }
}

更新当前账户下指定 Tweet 的 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

示例结果

{
  "request": {
    "params": {
      "tweet_id": 994747471329873920,
      "name": "新 Tweet 名称",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
      "coordinates": null,
      "retweeted": false,
      "name": "新 Tweet 名称",
      "conversation_settings": "EVERYONE",
      "source": "<a href="https://ads-api.x.com" rel="nofollow">X Ads API 内部测试 App</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        5
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "994747471329873920",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 994747471329873920,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Wed Jan 01 00:00:00 +0000 2020",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "你好",
      "lang": "en",
      "contributors": null,
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "utc_offset": null,
        "name": "Tushar Bhushan",
        "friends_count": 1065,
        "screen_name": "imit8me",
        "location": "加利福尼亚州旧金山",
        "protected": false,
        "url": "https://tushdante.github.io",
        "profile_image_url": "http://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_background_color": "C0DEED",
        "profile_use_background_image": true,
        "is_translator": false,
        "geo_enabled": true,
        "description": "开源开发者 / @twitter 合作伙伴工程师 / 太空旅行者 | 前 @sendgrid @keen_io 技术布道师",
        "profile_link_color": "1DA1F2",
        "id_str": "3271358660",
        "listed_count": 31,
        "default_profile_image": false,
        "followers_count": 407,
        "profile_image_url_https": "https://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_sidebar_border_color": "C0DEED",
        "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png",
        "favourites_count": 5993,
        "following": null,
        "default_profile": true,
        "withheld_in_countries": [],
        "id": 3271358660,
        "profile_background_tile": false,
        "contributors_enabled": false,
        "follow_request_sent": null,
        "created_at": "Tue Jul 07 22:34:58 +0000 2015",
        "profile_sidebar_fill_color": "DDEEF6",
        "translator_type": "regular",
        "lang": null,
        "profile_text_color": "333333",
        "notifications": null,
        "verified": false,
        "time_zone": null,
        "profile_banner_url": "https://pbs.twimg.com/profile_banners/3271358660/1474853576",
        "statuses_count": 500,
        "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png",
        "is_translation_enabled": false
      },
      "tweet_id": "994747471329873920"
    }
}

视频会话卡片

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

示例响应

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

获取与当前账号关联的特定视频会话卡片。

资源 URL

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

参数

名称	描述
account_id 必填	杠杆账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已验证用户关联。类型：string 示例：`18ce54d4x5t`
card_id 必填	本次请求中所操作的视频会话卡片的标识引用。类型：string 示例：`4i0ya`
with_deleted 可选	是否在结果中包含已删除项。类型：boolean 默认值：`false` 可能的取值：`true`，`false`

示例请求

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

示例响应

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_id": "5a86h",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "视频对话卡片",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "立即构建",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "X Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "开发者",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  }
}

POST accounts/:account_id/cards/video_conversation

为指定账户创建一个新的视频会话卡片。参阅上传媒体，了解将图像上传到我们的 endpoint 的实用信息。

资源 URL

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

参数

名称	描述
account_id required	目标账户的标识符。出现在资源路径中，通常是除了 GET accounts 之外所有广告主 API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
first_cta required	第一个选项的行动号召 (CTA) 话题标签。最大长度：20 个字符（不包括 #）。类型：string 示例：`#APIs`
first_cta_tweet required	点击第一个 CTA 时使用的 Tweet 文本。类型：string 示例：`Ads API`
media_key required	此卡片中使用的视频的媒体键。注意：视频必须在账户的媒体库中。注意：需要 16:9 的宽高比。类型：string 示例：`13_1168079965037467209`
name required	卡片的名称。类型：string 示例：`video conversation card`
thank_you_text required	点击 CTA 后显示的文本。最大长度：23 个字符。类型：string 示例：`Build it`
title sometimes required	卡片的标题，显示在视频下方和 CTA 上方。最大长度：23 个字符。类型：string 注意：如果未设置 `second_cta`，则为必需。示例：`Developers`
second_cta sometimes required	第二个选项的行动号召 (CTA) 话题标签。最大长度：20 个字符（不包括 #）。类型：string 注意：如果未设置 `title`，则为必需。示例：`#ShareAgain`
second_cta_tweet sometimes required	点击第二个 CTA 时使用的 Tweet 文本。注意：如果设置了 `second_cta`，则为必需。类型：string 示例：`I Heart @AdsAPI Again`
poster_media_key optional	此卡片中使用的海报图像的媒体键。如果未指定，将使用第一帧。注意：视频必须在账户的媒体库中。类型：long 示例：`3_882726458191298561`
third_cta optional	第三个选项的行动号召 (CTA) 话题标签。最大长度：20 个字符（不包括 #）。类型：string 示例：`#ShareMore`
third_cta_tweet sometimes required	点击第三个 CTA 时使用的 Tweet 文本。类型：string 注意：如果设置了 `third_cta`，则为必需。示例：`I Heart @TwitterDev`
fourth_cta optional	第四个选项的行动号召 (CTA) 话题标签。最大长度：20 个字符（不包括 #）。类型：string 示例：`#ShareExtra`
fourth_cta_tweet sometimes required	点击第四个 CTA 时使用的 Tweet 文本。类型：string 注意：如果设置了 `fourth_cta`，则为必需。示例：`I Heart @TwitterDev Again`
thank_you_url optional	与感谢文本一起显示的 URL。类型：string 示例：`https://example.com/thankyou`
unlocked_image_media_key optional	在即时解锁场景中使用的图像的 `media_key`。这是一个只写字段。在响应中，API 将为此图像提供一个 X URL。注意：图像必须在账户的媒体库中。类型：string 示例：`3_883112887618682880`
unlocked_video_media_key optional	来自 GET accounts/:account_id/media_library endpoint 的视频标识符，将在即时解锁场景中使用。类型：string 示例：`13_867520357225418752`

示例请求

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

示例响应

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

更新当前帐号下指定的视频会话卡片。请参阅Uploading Media，了解向我们的 endpoint 上传图像的实用信息。

资源 URL

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

参数

名称	描述
account_id 必需	所使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有广告主 API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
card_id 必需	您在请求中操作的视频对话卡片的引用。类型：string 示例：`5a86h`
first_cta 可选	第一个选项的行动号召 (CTA) 话题标签。最大长度：20 个字符（不包括 #）。类型：string 示例：`#APIs`
first_cta_tweet 可选	点击第一个 CTA 时要使用的 Tweet 文本。类型：string 示例：`X Ads API`
second_cta 可选	第二个选项的行动号召 (CTA) 话题标签。最大长度：20 个字符（不包括 #）。类型：string 注意：如果未设置 `title`，则为必需。示例：`#ShareAgain`
second_cta_tweet 可选	点击第二个 CTA 时要使用的 Tweet 文本。注意：如果设置了 `second_cta`，则为必需。类型：string 示例：`I Heart @AdsAPI Again`
third_cta 可选	第三个选项的行动号召 (CTA) 话题标签。最大长度：20 个字符（不包括 #）。类型：string 示例：`#ShareMore`
third_cta_tweet 可选	点击第三个 CTA 时要使用的 Tweet 文本。类型：string 注意：如果设置了 `third_cta`，则为必需。示例：`I Heart @TwitterDev`
fourth_cta 可选	第四个选项的行动号召 (CTA) 话题标签。最大长度：20 个字符（不包括 #）。类型：string 示例：`#ShareExtra`
fourth_cta_tweet 可选	点击第四个 CTA 时要使用的 Tweet 文本。类型：string 注意：如果设置了 `fourth_cta`，则为必需。示例：`I Heart @TwitterDev Again`
media_key 可选	此卡片中要使用的视频的媒体密钥。注意：视频必须在账户的媒体库中。注意：需要 16:9 的宽高比。类型：string 示例：`13_1168079965037467209`
name 可选	卡片的名称。类型：string 示例：`developers card`
poster_media_key 可选	此卡片中要使用的海报图像的媒体密钥。如果未指定，将使用第一帧。注意：图像必须在账户的媒体库中。类型：long 示例：`3_882726458191298561`
thank_you_text 可选	点击 CTA 后要显示的文本。最大长度：23 个字符。类型：string 示例：`Build it`
thank_you_url 可选	与感谢文本一起显示的 URL。类型：string 示例：`https://example.com/thankyou`
title 可选	卡片的标题，显示在视频下方和 CTA 上方。最大长度：23 个字符。类型：string 注意：如果未设置 `second_cta`，则为必需。示例：`Start a conversation`
unlocked_image_media_key 可选	在即时解锁场景中使用的图像的 `media_key`。这是一个只写字段。在响应中，API 将为此图像提供一个 X URL。注意：图像必须在账户的媒体库中。类型：string 示例：`3_883112887618682880`
unlocked_video_media_key 可选	来自 GET accounts/:account_id/media_library endpoint 的视频标识符，将在即时解锁场景中使用。类型：string 示例：`13_867520357225418752`

示例请求

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

示例响应

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

永久删除当前账户下的指定视频对话卡片。注意：这是一次硬删除，因此无法恢复已删除的卡片。

资源 URL

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

参数

名称	描述
account_id 必填	被使用账户的标识符。该值出现在资源路径中，且通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
card_id 必填	请求中所操作的视频会话卡片的标识引用。类型：string 示例：`4i0ya`

示例请求

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

示例响应

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

X Ads API

基础知识

资源

衡量

​概览

​卡片

​图像

​视频

​推广视频

​推广视频（Tweet 中）

​卡片中的推广视频

​常规信息

​使用指南

​预定的 Tweet

​介绍

​API endpoint

​预定 Tweet 管理

​预定的推广型 Tweet

​计划 Tweet 视图

​计划发布的 Tweet 创建：

​预定的 Tweet 变为“上线”：

​工作流程

​计划的 Tweet 上线时会发生什么？

​最佳实践

​媒体资料库

​简介

​API 端点

​添加到库

​请求参数

​属性

​使用说明

​识别卡片类型

​介绍

​使用 card_uri 识别 Tweet

​使用 preview_url 识别 Tweets

​获取卡片

​识别媒资

​介绍

​图像

​视频

​媒体库

​Tweets

​简介

​Nullcasted Tweets

​推广 Tweets

​Tweet ID

​轮播图

​介绍

​Endpoints

​JSON POST Body

​示例

​创意 metadata 标记

​介绍

​标记创意素材

​有问题？

​API 参考文档

​账号媒体

​GET accounts/:account_id/account_media

​资源 URL

​参数

​示例请求

​示例响应

​资源 URL

​参数

​示例请求

​示例响应内容

​资源 URL

​参数

​示例请求

​示例响应

​Cards

​资源 URL

​参数

​示例请求

​示例响应

​资源 URL

​参数

​示例请求

​示例响应

​POST accounts/:account_id/cards

概览

卡片

图像

视频

推广视频

推广视频（Tweet 中）

卡片中的推广视频

常规信息

使用指南

预定的 Tweet

介绍

API endpoint

预定 Tweet 管理

预定的推广型 Tweet

计划 Tweet 视图

计划发布的 Tweet 创建：

预定的 Tweet 变为“上线”：

工作流程

计划的 Tweet 上线时会发生什么？

最佳实践

媒体资料库

简介

API 端点

添加到库

请求参数

属性

使用说明

识别卡片类型

介绍

使用 card_uri 识别 Tweet

使用 preview_url 识别 Tweets

获取卡片

识别媒资

介绍

图像

视频

媒体库

Tweets

简介

Nullcasted Tweets

推广 Tweets

Tweet ID

轮播图

介绍

Endpoints

JSON POST Body

示例

创意 metadata 标记

介绍

标记创意素材

有问题？

API 参考文档

账号媒体

GET accounts/:account_id/account_media

资源 URL

参数

示例请求

示例响应

资源 URL

参数

示例请求

示例响应内容

资源 URL

参数

示例请求

示例响应

Cards

资源 URL

参数

示例请求

示例响应

资源 URL

参数

示例请求

示例响应

POST accounts/:account_id/cards

资源 URL

参数

组件

示例请求