跳转到主要内容
如需获取 X Ads API 历史版本的最新信息，请参阅下文。
版本路径发布日期弃用日期生命终止日期
12.0/12/2022 年 10 月 27 日待定待定
11.0/11/2022 年 3 月 31 日待定待定
10.0/10/2021 年 8 月 31 日2022 年 3 月 31 日2022 年 10 月 27 日
9.0/9/2021 年 3 月 2 日2021 年 8 月 31 日2022 年 3 月 31 日
8.0/8/2020 年 9 月 8 日2021 年 3 月 2 日2021 年 8 月 31 日
7.0/7/2020 年 3 月 3 日2020 年 9 月 1 日2021 年 3 月 2 日
6.0/6/2019 年 8 月 28 日2020 年 3 月 3 日2020 年 9 月 1 日
5.0/5/2019 年 2 月 28 日2019 年 8 月 28 日2020 年 3 月 3 日
4.0/4/2018 年 8 月 28 日2019 年 2 月 28 日2019 年 8 月 28 日
3.0/3/2018 年 2 月 1 日2018 年 8 月 28 日2019 年 2 月 28 日
2.0/2/2017 年 7 月 10 日2018 年 2 月 1 日2018 年 8 月 1 日
1.0/1/2016 年 3 月 31 日2017 年 7 月 7 日2018 年 1 月 10 日
0.0/0/2013 年 2 月 21 日不适用2016 年 10 月 31 日

​
概述

每个月，我们都会对 X Ads API 进行更新并推出若干新功能。这些更新几乎总是向后兼容，但我们每年确实会有少量破坏性变更。我们收到了开发者的反馈，指出 Ads API 快速迭代在实现新功能、处理弃用以及测试变更时会给他们的开发周期带来挑战。为改进在我们 Ads 平台上的开发者体验，我们引入了端点版本化的概念。 以下是我们讨论的一些概念定义： 版本：指任何 Ads API 请求的 URL 路径中出现的版本号，例如：GET //accounts。此类版本控制方式称为 URI 版本化。 破坏性变更：指任何需要开发者投入资源以维持现有功能的更改。这包括用于调查需要进行的更改、确定被弃用的功能/端点，以及最终实施所有这些更改所需的资源。破坏性变更示例包括：
  • 从 API 请求/响应中移除参数
  • 修改任何参数或端点的名称
  • 更改值的表示方式（preview_url → card_uri）
  • 更改端点行为（例如，异步与同步统计）
  • 添加/更改可选或必填参数（例如，将 name 设为请求中的必填字段）
弃用：被弃用的版本或产品将不再受支持，建议开发者停止使用这些 API。 下线：一旦某个产品或 API 下线，其相应的一组端点将无法再通过 API 访问。

​
版本管理策略

该策略的主要原则如下：
  1. 所有破坏性变更都会合并到一个新版本中
  2. 每当宣布新版本时，现有版本的弃用期为 6 个月
  3. 在任意时间点，API 将同时允许来自两个版本的请求，但其中较旧的那个将不再受支持
  4. 为了更快推动新产品的采用，这些产品将以持续发布的方式推出（不受版本节奏限制）
  5. 所有 API 响应都会包含一个 x-current-api-version，其值为当前 API 版本；当调用任何已弃用的 API 端点时，还会包含一个 x-api-warn 头
如果出现任何因根本性产品需求变更而必须进行的 API 破坏性变更（例如弃用多年龄段分桶定向），我们将提前 90 天发出通知以宣布该破坏性变更，并在通知发布至少 90 天后部署该破坏性变更

​
v9

今天（2021 年 3 月 3 日），X Ads API 第 9 版（v9）现已发布。本次版本旨在提升功能对齐度、简化广告系列创建流程，并对我们的 Cards 与 Mobile App Promotion 端点引入关键更新。 与以往版本相同，将提供为期 6 个月的过渡期以迁移到 v9。自 2021 年 8 月 31 日起，现有的第 8 版（v8）Ads API 将不再可用。我们鼓励所有开发者尽快迁移到最新版本的 Ads API，以避免任何服务中断。
注意： 自本次发布起，Ads API 第 7 版（v7）已终止生命周期，不再可用。
完整详情请参阅开发者论坛公告。

​
v8

今天（2020 年 9 月 20 日），我们发布了 X Ads API 的第 8 版，带来了全新的 Tailored Audiences 功能、提升了与 ads.x.com 的功能对齐，并改进了开发者体验。 与以往版本相同，我们将提供 6 个月的过渡期以迁移到 v8。自 2021-03-02 起，Ads API 第 7 版将不再可用。我们鼓励所有开发者尽快迁移到最新的 API 版本，以避免服务中断。 完整详情请参见开发者论坛公告。

​
v7

今天（2020 年 3 月 20 日），我们发布了 X Ads API 的第 7 版，旨在提升与 ads.x.com 的功能对齐度。 与以往版本相同，将提供 6 个月的过渡期以迁移到 v7。自 2020-09-01 起，Ads API 第 6 版将不再可用。我们鼓励所有开发者尽快迁移到最新的 API 版本，以避免任何服务中断。Ads API 第 5 版已到达生命周期终点，现已停止提供。 详情请参阅开发者论坛公告。

​
v6

今天（2019 年 8 月 28 日），X 推出了 Ads API v6，更新重点在于提升一致性并改进开发者体验。 本次发布包含用于检索 Tweet 的新端点、Promoted Accounts 的统计数据、按名称搜索实体的功能，以及当前正在处理的异步分析作业数量信息。此外，我们对使用媒体的端点以及目标定位条件端点进行了以一致性为导向的更新。最后，我们对部分参数名称和响应属性进行了小幅更新，并弃用了 Scoped Timeline 端点。 完整详情请参阅开发者论坛公告。

​
v5

今天（2019 年 2 月 28 日），X 推出 Ads API v5，本次更新重点在于提升扩展性与效率。 此版本包括：用于确定在给定时间范围内哪些实体处于活跃状态的新端点、面向 Media Creatives（即 X Audience Platform 上的串流内视频和图片）的统计、按卡片 URI 获取多张卡片的能力，以及在检索定向条件和其他实体方面更高的灵活性。此外，我们修复了一些错误，并更新了参数名称和响应属性。最后，非媒体应用卡片以及 POST accounts/:account_id/account_media 端点已被弃用。 与以往版本一样，将有 6 个月的过渡期以迁移到 v5。自 2019-08-28 起，Ads API 第 4 版将不再可用。我们鼓励所有合作伙伴尽快迁移到最新版本的 API，以避免任何服务中断。Ads API 第 3 版已到达生命周期终点，且不再可用。

​
新增

确定哪些实体处于活动状态 The Active Entities endpoint signifies whether analytics metrics for ads entities have changed. Designed to be used in conjunction with the analytics endpoints, Active Entities works by specifying an entity type and a date range—a maximum of 90 days—and returns an array of entity IDs that your platform should request analytics for. IDs other than the ones returned should not be queried in subsequent analytics requests. This endpoint supports the following entity types:CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, and PROMOTED_TWEET. MEDIA_CREATIVE 指标 Ads API 的分析端点现已提供 Media Creative 实体的指标。Media Creative 用于在 X Audience Platform 上推广贴片广告或图片。X Ads 界面会在“In-stream videos”和“Display creatives”选项卡下显示 Media Creative 指标。同步 和 异步 分析端点现均支持 MEDIA_CREATIVE 实体枚举。 获取多张卡片 在为按 card URI 值检索单张卡片而设计的 v3 版本 端点基础上进行改进，现在可以使用 GET accounts/:account_id/cards/all 端点获取多张卡片。现在，您无需为每张卡片分别发起请求，一次请求最多可检索 200 张卡片。 需要注意两点：
  1. URL 路径现为 accounts/:account_id/cards/all。（先前的路径已不可用。）这样做是为了与用于按 ID 检索卡片的端点保持一致。
  2. 必填请求参数现命名为 card_uris（复数）。
检索的灵活性 GET accounts/:account_id/targeting_criteria 端点现支持多个 line item ID。参数 line_item_ids（最多可接收 200 个 ID）为必填项。此前仅接受单个 line item，导致同步困难。通过此变更，现在可以在更短时间内检索更多定向信息。 以下端点也现支持多个 line item ID，但对这些端点而言，line_item_ids 参数为可选：

​
变更

检索草稿广告系列和订单项 检索草稿广告系列和订单项的方式已更新。现在，当将 with_draft(boolean) 参数设置为 true 时，将返回草稿和非草稿实体。这与检索已删除实体的方式一致（即使用 with_deleted）。此前，同时获取草稿和非草稿实体至少需要两次请求。现在，一次 API 调用即可完成。 | v4 | v5 | | :--- | :--- | :--- | | draft_only | with_draft | | Network Activation Duration 定向 Ads API 已修复一个显示问题：在添加 Network Activation Duration 定向后，响应中的定向类型包含了 _IN_SEC 后缀。由于 Network Activation Duration 始终以月为单位表示，引用秒会引起混淆。该修复使表示保持一致并减少混淆。 | v4 | v5 | | :--- | :--- | :--- | | NETWORK_ACTIVATION_DURATION_IN_SEC | NETWORK_ACTIVATION_DURATION | | 总数与游标 在 v5 中，with_total_count 和 cursor 是互斥的。在请求中同时指定两者将返回 EXCLUSIVE_PARAMETERS 错误码。在 v5 之前，指定 cursor 时会忽略 with_total_count。此更改使两者之间的关系更加明确。

​
已移除

将从 Ads API 响应中移除三个字段：preview_url、account_id 和 parent_ids。对这三项的工程改动最小。
  • 在 v4 中，我们宣布 cards 的 preview_url 响应参数始终为 null。此次迁移的最后一步是从所有 cards 响应中移除 preview_url。
  • 将从以下资源中移除 account_id 响应属性，因为广告账户 ID 已存在于 URL 以及 request.params 中。（有意将资金工具从此列表中排除，因为在可能的情况下，父 ID 应出现在响应对象中，而账户 ID 是资金工具的父实体。）
    • 账户媒体
    • 应用事件提供方
    • 应用事件标签
    • 广告系列
    • 卡片
    • 线项
    • 可推广用户
    • 定向条件
  • 对于 GET accounts/:account_id/targeting_criteria 请求，我们不再返回 parent_ids 字段，因为它始终是空数组。
非媒体应用卡片 在 v5 中，不再支持非媒体应用卡片。此前 已移除创建或编辑非媒体应用卡片的能力。现在，将弃用该资源剩余的端点。
  • 注意：这不影响图片和视频应用下载卡片。
账户媒体创建 POST accounts/:account_id/account_media 端点在 v5 中不再可用。该资源的其他端点不受影响。此变更的原因是，当将媒体添加到 Media Library 时，在某些情况下，这些资产会自动被添加为 Account Media 实体，而尝试将已存在的资产再次添加到 Account Media 资源会导致错误。以下情况会发生此问题。
  • 添加到 Media Library 的 AMPLIFY_VIDEO 资产会自动作为 Account Media 资产添加，并使用 PREROLL 创意类型。
  • 添加到 Media Library 且具有特定尺寸的图片会自动作为 Account Media 资产添加。创意类型（例如 INTERSTITIAL）取决于图片尺寸。（有关尺寸，请参阅我们的 Enumerations 页面。）

​
v4

Ads API 的第 4 版将于今日（2018 年 8 月 28 日）发布。 本次版本为我们的 Audiences 产品带来改进，包括由更健壮的受众处理后端驱动的全新 API 接口。第 4 版还包含一组用于管理用户、账户和税务设置的端点。此外，将弃用 accounts/:account_id/videos 端点。本次发布还包含少量参数和响应名称的更改。 与第 3 版相同，我们提供 6 个月的过渡期。自 2019-02-28 起，Ads API 的第 3 版将不再可用。我们鼓励所有合作伙伴尽快迁移到最新的 API 版本，以避免任何服务中断。有关我们的版本策略的详细信息，请参阅 Versions 页面。

​
新增

Audience API 全新的 Audiences API 构建于我们新的人群处理后端之上，具备更高的稳健性与可靠性。这个新端点允许合作伙伴为单个用户提供多种用户标识符类型，从而利用更多信号进行匹配。新的 Audience 端点参考文档见此处。我们计划在今年剩余时间持续发布该产品的更新与改进。 以下端点由于功能重叠将在 v4 中不再提供（它们在 v3 中仍可使用，并将在 v3 停用时完全下线）：
  • TON Upload：
    • GET accounts/:account_id/tailored_audience_changes
    • GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
    • POST accounts/:account_id/tailored_audience_changes
    • PUT accounts/:accounti_d/tailored_audiences/global_opt_out
  • Real Time Audiences：
    • POST tailored_audience_memberships
最后，在版本 4 中，将从_所有_ Tailored Audiences 端点的请求与响应中移除 list_type 参数。 Settings Endpoints 我们现已提供功能，允许账户管理员设置和更新用户、账户及税务设置。User settings对应于给定广告账户的用户联系偏好。通过 PUT accounts/:account_id 端点，广告主现在可以更新其账户名称与行业类型。最后，tax settings 端点允许位于征收增值税（VAT）国家/地区的广告主更新信息，例如公司名称、地址、VAT ID，以及账户是由广告主自有还是由代表广告主投放广告的代理机构所有。

​
已更改

Universal Lookalike 重命名 我们正在更新 POST accounts/:account_id/line_items 和 PUT accounts/:accountit/line_items/:line_item_id 端点的 lookalike_expansion 参数枚举值。
v3v4
NARROWDEFINED
BALANCEDEXPANDED
全局使用 country_code 作为在 Ads API 上推动一致性的更大举措的一部分，我们将以下端点中的参数由 app_country_code 重命名为 country_code。 这不会影响这些参数的行为或可接受的取值，仅是命名上的更改。 preview_url 始终为 null 正如在 v3 公告中所承诺的，所有现有卡片现在都有 card_uri。因此，preview_url 的值将始终为 null。 提醒：使用其 card_uri 将卡片与 Tweet 关联。请参阅以下示例请求。 $ twurl -X POST -H ads-api.x.com “/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496”

​
已移除

视频端点 accounts/:account_id/videos 端点在 v4 中将不再可用。随着 Media Library 端点的引入，此端点已被淘汰。请参阅下方用法对比。
  • v3 视频端点：twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos"
  • v4 媒体库视频端点：twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
Media Library 端点与视频端点功能完全等效，并且还支持更多功能，例如处理图像和 GIF。请合作伙伴仅使用 Media Library 进行各类媒体管理。 Tweet 视图中的 as_user_id GET accounts/:account_id/tweet/preview/:tweet_id 端点上的 as_user_id 参数将不再被接受。预览将始终以 Tweet 作者的身份呈现。

​
v3

Ads API 的第 3 版于 2018 年 2 月 1 日发布。Ads API 的第 2 版将于 2018 年 8 月 1 日终止服务。 此版本包含全新的 Audience Intelligence 产品、对 Media Library 的访问，以及优化的卡片工作流。我们还宣布弃用 PUT accounts/:account_id/targeting_criteria 端点。最后，第 3 版还包含少量参数与响应变更，以及更低的批处理大小上限。 与第 2 版一样，我们为合作伙伴提供了6 个月的过渡期。自 2018-08-01 起，Ads API 的 v2 将被停用。我们鼓励所有合作伙伴和开发者尽快迁移到 v3。 Audience Intelligence Audience Intelligence 可提供与指定 X 受众最相关的热门话题标签、@账号和事件的实时洞察。例如，输入“美国 18–34 岁男性”，你将会看到 #nintendoswitch、#cardinal 和 @ricegum 在该受众中呈上升趋势。 Audience Intelligence 的端点将提供以下功能：
  • 针对输入受众，检索最相关的话题标签、@账号和事件。
  • 针对输入受众，检索关键的人口统计信息（如年龄、性别和家庭收入）。
  • 基于关键词，检索 Tweet 量的时间序列。
Media Library Media Library 提供管理广告账户的图片、GIF 和视频的能力。这些媒体对象可用于 Tweets 并用于创建卡片。它们也可以在多个创意中复用，从而无需多次上传相同素材。 库中的对象通过 media_key 标识。Media key 是字符串值，例如：13_875943225764098048。在 Ads API 中，我们正逐步在所有媒体上采用 media key。 改进的卡片工作流 我们所有的卡片端点现在都支持 media key。这使得可以使用 Media Library 中的对象来创建或更新卡片。 此外，我们引入了两个用于检索卡片详情的新端点。例如，这些端点可通过指定 card_uri 或 id 来查询用于 Tweets 或 Scheduled Tweets 的卡片。此前，这无法实现。

​
其他更改

除了这些新功能之外，我们还在第 3 版中包含以下更改。 新增 变更
  • 现在定位条件批处理的最大数量为 500。
  • 响应属性 card_uri 和 preview_url 现在互斥。当卡片具有 card_uri 时，preview_url 为 null；当卡片不具有 card_uri 时，只会返回 preview_url。
    • 自 2018-01-29 起创建的所有卡片都会具有 card_uri。
    • 到第 4 版时，所有现有卡片都会具有 card_uri。
  • 不再允许“创建”包含 5:2 图像的卡片。虽然“现有”的 5:2 图像类卡片仍可使用，但我们鼓励合作伙伴改用性能更高的 1.91:1 或 1:1 纵横比（在受支持的情况下）。
移除 说明 Video Website Cards 和 Scheduled Tweets 现已退出测试阶段。请参阅 此帖 了解我们自发布以来对 Scheduled Tweets 所做的更改。这包括为 Scheduled Tweets 生成 HTML 预览 的功能。

​
v2

Ads API 第 2 版已于 2017 年 7 月 10 日发布。Ads API 第 1 版将于 2018 年 1 月 10 日停止服务。 重大变更/弃用
  • total_count 现为可选响应属性。仅当 with_total_count 设置为 true 时可用
  • 在 line_items 和 campaigns 的请求与响应对象中，paused 和 draft_only 字段被合并为单一的 entity_status 参数
  • 在 POST accounts/:account_id/tweet 和 GET accounts/:account_id/tweet/preview 端点上，status 参数已更名为 text
  • GET targeting_criteria/locations 端点的 location_type 枚举现为复数：COUNTRY 改为 COUNTRIES，REGION 改为 REGIONS，以此类推。唯一例外是，在 v2 中，CITY 改为 METROS，以准确反映该位置类型指代指定市场区域（DMA）或“都市圈”
  • 在 PUT accounts/:account_id/promoted_tweets 端点上移除了 display_properties。该值也将不再作为响应的一部分返回
  • 因上述变更，不再支持更新（PUT）promoted_tweets 实体
  • GET accounts/:account_id/promoted_tweets 端点的 line_item_id 参数已移除
  • v2 端点不再支持创建 5:2 的 Website Card
  • 响应属性 data_type 不再返回
新增功能
  1. Cards v2
  2. 草稿广告系列/line item 的创建与激活
  3. Scheduled Tweets
  4. 异步作业摘要
Cards v2
  • 将卡片与 Tweet 关联时，应使用 card_uri 请求参数，而非把 preview_url 附加到 Tweet 文本中
  • 若响应（在创建卡片步骤中）未返回 card_uri 参数，则使用 preview_url
  • 所有新的卡片格式都将原生支持于 API，并利用 card_uri 参数
新 Card 格式： 草稿广告系列 草稿广告系列可通过 GET accounts/:account_id/camapaigns 端点查看。在 v2 中，现在可以通过 API 创建/激活草稿广告系列。
草稿广告系列草稿广告组
funding_instrument_idcampaign_id
nameobjective
start_timeproduct_type
placements
备注
  • 草稿广告组或广告系列只能将 entity_status 从 DRAFT 转为 PAUSED 或 ACTIVE
  • 若要激活整个广告系列（包含多个广告组），该广告系列下的每个广告组以及广告系列本身都必须将 entity_status 设置为 ACTIVE。
  • 若要更改任何广告系列或广告组的 entity_status，请使用相应的 PUT 端点。
Scheduled Tweets

​
v1

Ads API 的第 1 版于 2016 年 3 月 31 日发布，并将于 2018 年 1 月 10 日停止服务。 第 1 版的变更：
  • 版本控制相关支持
  • CUSTOM 目标 已不再受支持
  • 批量端点 现已全面开放
  • 触达预估变更(https://developer.x.com/en/docs/ads/campaign-management/api-reference/reach-estimate.html#get-accounts-account-id-reach-estimate):
  • 为提供更准确的触达预估，该端点现已考虑预算因素。现在需要以下参数：
    • [新增] campaign_daily_budget_amount_local_micro
    • currency
    • bid
    • objective
  • 响应对象已更新，现在会为响应值返回区间。
  • infinite_count 已重命名为 infinite_bid_count，以免对其用途产生混淆
  • 除 count 和 infinite_bid_count 外，现在还将返回以下新的数据项：
    • impressions
    • engagements
    • estimated_daily_spend_local_micro
  • 定向受众的数据类型变更
  • 我们已在所有响应中将 Tailored Audiences 的 data_type 从 tailored_audiences 更改为 tailored_audience。
  • 共享定向受众现已作为“仅限 API”的测试版提供。共享定向受众允许在多个广告账户之间复用同一个受众。使用 POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions（及相关）端点来管理你希望在各广告账户间共享的定向受众的权限。
  • 在为广告主账户收集绩效分析方面的重大改进：
  • 为符合我们的最佳实践，我们现在仅允许通过同步统计端点提取最多连续 7 天的数据。
  • 为简化获取指标，我们已将 metrics 参数替换为新的 metric_groups 参数。开发者只需在请求中指定希望返回的指标组即可。
    • 对于不适用于某个实体的指标请求，将从响应中排除，并以 null 值表示。这些指标不会计入你的分析成本上限。
  • 响应已大幅简化，并将更贴近我们 UI 中指标的呈现方式。
    • 之前，我们为每个投放位置分别提供独立指标（搜索中的 Promoted Tweets、时间线中的 Promoted Tweets、个人资料与 Tweet 详情中的 Promoted Tweets、X Audience Platform）。现在，我们将为每个位置返回一组标准化的指标（不再使用 promoted_tweet_timeline_impressions、promoted_tweet_search_impressions、promoted_tweets_profile_impressions、promoted_tweets_tpn_impressions）。当在以下任一类别中请求时，将以单一指标 impressions 提供（适用于所有指标）：
    • ALL_ON_TWITTER
    • PUBLISHER_NETWORK
    • 当你发起请求时，你将获得单一的 impressions 指标，便于与我们 UI 中的数值对齐。
    • 你必须分别发起两次查询才能获取 ALL_ON_TWITTER 和 PUBLISHER_NETWORK 的数据，因为二者不可合并。
  • 根据开发者反馈，异步统计端点现已上线！
    • 一组新的端点可用于以异步方式请求统计数据，适用于无需立即获取的数据或历史数据拉取。
    • 通过一个新的单一端点将统计任务加入队列。我们会在资源允许的情况下提取你请求的数据。
    • 你可以查询作业状态端点以确定数据是否可用。
    • 一旦数据可用，我们将提供一个取回ID，供你下载JSON响应，其结构将与同步端点的响应一致。
    • 在单个作业中可查询最长90天、最多20个实体的数据。
  • 请查看我们的 Analytics v1 迁移指南，其中包含从 v0 指标到 v1 指标的对应关系。
  • 沙盒改进 * 您现在可以在沙盒环境中创建多个测试广告账户。 * 您现在仅可在沙盒环境中为测试广告账户创建多个资金工具，从而覆盖我们所有资金工具类型的测试。此前仅提供 CREDIT_CARD 资金来源供测试。 * 想测试测试版功能？您现在可以在沙盒环境中为某个账户切换功能开/关，以满足测试需求。

​
v0

Ads API 的 0 版于 2013 年 2 月 21 日正式发布，并提供支持直至 2016 年 10 月 31 日。 所有 0 版的分析端点均已弃用，并将在 2016 年 10 月 31 日后下线。这些端点已在 1 版中由 3 个分析端点取代。 在 1 版中，触达预估端点的行为有所调整。