有关 Twitter 广告 API 历史版本的最新信息，请参见下面的信息。

概述

每个月，我们都会对 Twitter 广告 API 做出更改并推出几项新功能。虽然这些更改几乎都可向后兼容，但我们往往每年都会做出一些重大变更。开发者已向我们反馈当涉及到实施新功能、处理弃用及测试变更时我们快速变更广告 API 的节奏对他们的开发周期所产生的影响。我们希望使用广告平台提升开发者的体验，因此引入了端点版本控制概念。

我们所讨论的部分概念的定义：

版本：是指任何 Ads API 请求的 URL 路径中存在的版本号，例如：GET /{version_number}/accounts。 这种版本控制称为 URI 版本控制。

重大更改：重大更改是需要开发者资源来维护现有功能的任何更改。这些资源包括用于研究需做出的更改、确定要弃用的功能/端点以及最终实施这些所有更改的资源。重大更改示例如下：

• 从 API 请求/响应中删除某一参数

• 修改任何参数或端点的名称

• 更改值的表示法 (preview_url → card_uri)

• 更改端点行为（例如异步与同步统计）

• 添加/更改可选或必需参数（例如使 name 成为请求中的必需字段）

弃用：我们将不对已弃用版本或产品提供支持，并且建议开发者停止使用这些 API。

废止：产品或 API 废止后，相应的端点组将无法再通过该 API 进行访问。

版本控制策略

版本控制策略的主要原则如下：

1. 将所有重大更改捆绑到新版本中

2. 在新版本宣布 6 个月后弃用现有版本

3. 在任何给定时间，API 允许两个版本同时发出请求，但其中的较旧版本将不受支持

4. 为实现快速采用新产品，我们将持续不断地（不按版本控制的节奏）发布新产品

5. 在调用任何已弃用的 API 端点时，所有 API 响应都将包含设置为 API 当前版本的 x-current-api-version，除此之外，还包含 x-api-warn 标头。

如有任何需要重大 API 更改的基本产品要求更改（例如弃用多年龄段定位），我们会提前 90 天发出通知，公告该重大更改，并会在通知发出至少 90 天后部署该重大更改

v9

今天起，即 2021 年 3 月 3 日起，Twitter 广告 API 第 9 版 (v9) 已可用。此版本旨在增强功能奇偶校验、简化广告活动的创建，并为卡片和移动应用推广端点引入关键更新。

对于先前的版本，有 6 个月迁移到 v9 的过渡期。从 2021 年 8 月 31 日开始，现有的广告 API 第 8 版 (v8) 不再可用。我们鼓励所有开发者尽快迁移到最新广告 API 版本，以避免任何服务中断。

注意：从此版本开始，广告 API 第 7 版 (v7) 已达到生命周期末尾，不再可用。

有关详细信息，请参见开发者论坛公告。

v8

今天，即 2020 年 9 月 20 日，我们推出了 Twitter 广告 API 第 8 版，旨在引入新的自定义受众功能，增强与 ads.twitter.com 的功能奇偶校验，并改进开发者体验。

对于先前的版本，有 6 个月迁移到 v8 的过渡期。从 2021 年 3 月 2 日开始，广告 API 第 7 版不再可用。我们鼓励所有开发者尽快迁移到最新 API 版本，以避免任何服务中断。

有关详细信息，请参见开发者论坛公告。

v7

今天，即 2020 年 3 月 20 日，我们推出了 Twitter 广告 API 第 7 版，旨在提高与 ads.twitter.com 的功能奇偶校验。

对于先前的版本，有 6 个月迁移到 v7 的过渡期。从 2020 年 9 月 1 日开始，广告 API 第 6 版不再可用。我们鼓励所有开发者尽快迁移到最新 API 版本，以避免任何服务中断。广告 API 第 5 版已达到生命周期末尾，不再可用。

有关详细信息，请参见开发者论坛公告。

v6

今天（2019 年 8 月 28 日），Twitter 推出了广告 API v6，此次更新重点是提高一致性和改善开发者体验。

此版本提供了一个用于检索推文的新端点、推广账号的统计信息、按名称搜索实体的功能，以及当前正在处理的异步分析作业数量的相关信息。此外，我们还对使用媒体的端点和定位标准端点进行了以一致性为重点的更新。最后，我们对部分参数名称和响应属性进行了小幅更新，并开始停用限定时间线端点。

有关详细信息，请参见开发者论坛公告。

v5

Twitter 于 2019 年 2 月 28 日推出广告 API v5，其中的更新侧重于实现规模和效率。

此版本包括一个用于确定在给定时间范围内活动的实体的新端点、媒体素材的统计（即 Twitter 受众平台上的流媒体广告视频和图片）、用于通过卡片 URI 获得多张卡片的功能以及检索定位标准和其他实体的灵活性。此外，我们还修复了一些缺陷并更新了参数名称和响应属性。最后，弃用了非媒体应用卡片和 POST accounts/:account_id/account_media 端点。

对于先前的版本，有 6 个月迁移到 v5 的过渡期。从 2019 年 8 月 28 日 开始，广告 API 第 4 版将不再可用。我们鼓励所有合作伙伴尽快迁移到最新 API 版本，以避免任何服务中断。广告 API 第 3 版已达到生命周期末尾，不再可用。

新功能

确定活动实体

活动实体端点表示广告实体的分析指标是否发生更改。活动实体专门与分析端点一起使用，其通过指定实体类型和日期范围（最长 90 天）来实现，并返回你的平台应该请求分析的实体 ID 数组。不应在后续分析请求中查询已返回 ID 除外的 ID。

此端点支持以下实体类型： CAMPAIGN、FUNDING_INSTRUMENT、LINE_ITEM、MEDIA_CREATIVE 和 PROMOTED_TWEET。

MEDIA_CREATIVE 统计

广告 API 分析端点现在提供媒体素材实体的指标。媒体素材是指流媒体广告或图片在 Twitter 受众平台上的推广方式。在 Twitter 广告用户界面上，媒体素材指标显示在“流媒体广告视频”和“展示素材”选项卡下。同步和异步分析端点现在均支持 MEDIA_CREATIVE 实体枚举。

获取多张卡片

对专门通过卡片 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 端点现在支持多个行项目ID。最多可接受 200 个 ID 的 line_item_ids 为必需参数。此前，只能接受一个行项目，因此较难同步。做出此更改后，可以花更少的时间检索更多定位。

以下端点现在还支持多个行项目 ID，但 line_item_ids 参数对于这些端点为可选参数。

• GET accounts/:account_id/line_item_apps
• GET accounts/:account_id/media_creatives
• GET accounts/:account_id/promoted_accounts
• GET accounts/:account_id/preroll_call_to_actions

更改的内容

检索广告活动草稿和行项目

更新了广告活动草稿和行项目的检索方式。现在，将 with_draft(boolean) 参数设为“true”后，将会同时返回草稿和非草稿实体。这与检索已删除实体（即使用 with_deleted）的方式一致。此前，要同时获取草稿和非草稿实体，至少需要两个请求。现在只需一个 API 调用即可实现。

网络激活时长定位

添加网络激活时长定位后，响应中的定位类型包含 _IN_SEC 后缀，广告 API 现在已经解决了此显示问题。由于网络激活时长一直以月为单位，引用秒容易令人混淆。此修复实现表示法的一致性并减少了混淆。

总计计数和光标

在 v5 中，with_total_count 和 cursor 相互排斥。如果在请求中同时指定二者，则会返回 EXCLUSIVE_PARAMETERS 错误代码。在 v5 之前的版本中，当请求中指定 cursor 时，会忽略 with_total_count。此更改使这种互斥成为显式关系。

删除的内容

从广告 API 响应中删除了三个字段：preview_url、account_id 和 parent_ids。删除这三个字段需要极少的工程工作。

• 在 v4 中已公告卡片的 preview_url 响应参数始终为空。此迁移的最后一步是，从所有卡片响应中删除 preview_url。
• 因为 URL 和请求参数中已存在广告账号 ID，则以下资源将删除 account_id 响应属性。（此列表特意排除了支付手段，因为父级 ID 应该尽可能出现在响应对象中且账号 ID 是支付手段的父实体。）
  • 账号媒体
  • 应用事件提供程序
  • 应用事件标记
  • 广告活动
  • 卡片
  • 行项目
  • 可推广用户
  • 定位标准
• 对于 GET accounts/:account_id/targeting_criteria 请求，由于 parent_ids 字段一直是空数组，因此我们不再返回此字段。

非媒体应用卡片

v5 将不再支持非媒体应用卡片。 先前，已经删除了创建或编辑非媒体应用卡片的功能。现在，将弃用用于此资源的剩余端点。

• 注意：这不会影响图片和视频应用下载卡片。

账号媒体创建

v5 不再提供 POST accounts/:account_id/account_media 端点。此资源的其他端点将不受影响。做出此更改的原因是，有时将媒体添加至媒体库时，这些资产会自动添加为账号媒体实体，尝试将已有资产添加到账号媒体资源会导致错误。在以下情况下会发生此问题。

• 添加至媒体库的 AMPLIFY_VIDEO 资产自动添加为 PREROLL 素材类型的账号媒体资产。
• 添加至媒体库的特定尺寸的图片自动添加为账号媒体资产。素材类型（例如 INTERSTITIAL）取决于图片尺寸。（关于尺寸，请参见枚举页面。）

v4

广告 API 第 4 版于 2018 年 8 月 28 日发布。

此版本包含对我们的受众产品的改进，包括由更稳健的受众处理后端提供支持的全新 API 接口。第 4 版还包含一组用于管理用户、账号和税务设置的端点。此外，将弃用 accounts/:account_id/videos 端点。在此版本中，还对参数和响应名称做了一些次要更改。

对于第 3 版，我们提供 6 个月的过渡期。从 2019 年 2 月 28 日开始，广告 API 第 3 版不再可用。我们鼓励所有合作伙伴尽快迁移到最新 API 版本，以避免任何服务中断。请参见版本页面了解有关版本控制策略的详细信息。

新功能

受众 API

新受众 API 构建于我们全新的受众处理后端之上，该处理后端增强了稳健性和可靠性。此新端点允许合作伙伴为单个用户提供多个用户标识符类型，这意味着我们能够使用额外信号进行匹配。可在此处查看该新受众端点的参考文档。我们计划在今年剩下的时间里继续发布此产品的更新和改进。

由于功能重复，以下端点在 v4 中将不再可用（在 v3 中，这些端点仍然可用，在 v3 不再可用时才完全废止）：

• TON 上传：
  • 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
• 实时受众：
  • POST tailored_audience_memberships

最后，第 4 版将从所有自定义受众端点上的请求和响应中移除 list_type 参数。

设置端点

账号管理员现在能够设置及更新用户、账号和税务设置。用户设置对应于给定广告账号的用户特定联系首选项。使用 PUT accounts/:account_id 端点，广告商现在可以更新自己的账号名称和行业类型。最后，税务设置端点允许收取增值税 (VAT) 的国家/地区的广告商更新诸如公司名、地址、增值税 ID 以及账号是广告商还是代表该广告商广告的代理所拥有等信息。

更改的内容

通用相似重命名

我们将更新 POST accounts/:account_id/line_items 和 PUT accounts/:accountit/line_items/:line_item_id 端点上 lookalike_expansion 参数的枚举值。

在任何位置使用 country_code

为了进一步提高广告 API 上的一致性，我们将以下端点上的参数从 app_country_code 重命名为 country_code。

• POST accounts/:account_id/cards/image_app_download
• PUT accounts/:account_id/cards/image_app_download/:card_id
• POST accounts/:account_id/cards/video_app_download
• PUT accounts/:account_id/cards/video_app_download/:card_id

此更改不会影响这些参数的行为或接受值，只是命名更改。

preview_url 始终为空

如 v3 通告中所承诺，所有现有卡片现在将都具有 card_uri。因此，preview_url 值将始终为 null。

我们在此提醒，请使用卡片的 card_uri 值将卡片与推文关联。请参见下面的示例请求。

$ twurl -X POST -H ads-api.twitter.com "/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496"

删除的内容

视频端点

accounts/:account_id/videos 端点在 v4 中将不再可用。引入了媒体库端点，此端点已作废。请参见下面的使用对比。

# v3 videos endpoint
$ twurl -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/videos"

# v4 media library endpoint for videos
$ twurl -H ads-api.twitter.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

媒体库端点完全与视频端点对等，还支持更多功能，例如处理图片和 GIF 的功能。我们要求合作伙伴只将媒体库用于任何媒体管理。

推文视图中的 as_user_id

将不再接受 GET accounts/:account_id/tweet/preview/:tweet_id 端点上提供的 as_user_id 参数。预览将始终呈现为推文的作者。

v3

广告 API 第 3 版已于 2018 年 2 月 1 日发布。广告 API 第 2 版的生命周期于 2018 年 8 月 1 日结束。

此版本包括我们新的受众智能产品、媒体库的访问以及卡片工作流程改进。我们还公告弃用 PUT accounts/:account_id/targeting_criteria 端点。最后，第 3 版包含一些次要的参数和响应更改和较低的批处理大小限制。

对于第 2 版，我们给予合作伙伴 6 个月的过渡期。从 2018-08-01 开始，将关闭广告 API v2。我们鼓励所有合作伙伴和开发者尽快迁移到 v3。

受众智能

受众智能提供与给定 Twitter 受众最相关的热门话题标签、@用户名和事件的实时洞察。例如，输入“Male 18-34 in the US”，你便会在此受众中看到“#nintendoswitch”、“#cardinal”和“@ricegumtrending”。

受众智能端点提供以下功能：

• 根据输入的受众，检索热门相关话题标签、@用户名和事件。
• 根据输入的受众，检索关键人口统计信息（例如年龄、性别和家庭收入）。
• 根据关键字，检索推文量时间序列

媒体库

媒体库能够让你管理广告账号的图片、GIF 和视频。这些媒体对象可用于推文中，并可用于创建卡片。它们也可以复用在多个素材中，而无需多次上传相同资产。

媒体库中的对象由 media_key 进行标识。媒体密钥是如下格式的字符串值：13_875943225764098048，示例。在广告 API 中，我们正将媒体密钥用于所有媒体。

卡片工作流程改进

我们所有的卡片端点现在均支持媒体密钥。这使媒体库中的对象可用于创建或更新卡片。

此外，我们推出了两个新端点，用于检索卡片详情。这些端点可用于查找推文或预排期推文中使用的卡片，例如通过指定 card_uri 或 id 来查找。以前，无法进行这种查找。

其他更改

除上述新功能之外，我们还对第 3 版做了以下更改。

新功能

• GET insights/keywords/search 端点响应现在包含 related_keywords 属性，该属性具有与输入关键字相关的 30 个词语。

更改的内容

• 现在，最大定位标准批量大小为 500。
• card_uri 和 preview_url 响应属性现在相互排斥。如果卡片具有 card_uri，则 preview_url 将为空。如果卡片没有 card_uri，则将只返回 preview_url。
  • 2018 年 1 月 29 日之后创建的所有卡片都具有 card_uri。
  • 在第 4 版中，所有现有卡片都将具有 card_uri。
• 将无法再使用 5:2 图片创建卡片。虽然现有基于 5:2 图片的卡片仍可使用，但我们鼓励合作伙伴改用效果更好的 1.91:1 或 1:1 宽高比图片（如果受支持）

删除的内容

• PUT accounts/:account_id/targeting_criteria 端点将不再可用。我们决定做出此更改的原因是，此端点的替换行为让广告商困惑不解，并且此端点与我们一次更新一个资源的其他 PUT 端点不一致。合作伙伴应改用 POST batch/accounts/:account_id/targeting_criteria 端点，其提供更高的灵活性，包括能够在一个请求中同时添加和删除定位。
• 将不再针对支付手段返回“paused”响应属性。改用 entity_status 响应属性来确定支付手段是否被暂停。此外，由于“paused”和“cancelled”对应同一个值，因此也不再返回“cancelled”。
• 我们已将 card_id 参数从 GET accounts/:account_id/tweet/preview 端点中删除。
• 由于无法检索已删除的预排期推文，因此将不再支持 with_deleted 参数。
• 由于这些实体不可能处于草稿状态，因此已从以下端点删除了 draft_only 参数：
  • GET accounts/:account_id/targeting_criteria
  • GET accounts/:account_id/promoted_tweets
  • GET accounts/:account_id/promoted_accounts
  • GET accounts/:account_id/media_creatives
  • GET accounts/:account_id/preroll_call_to_actions

注意

视频网站卡片和预排期推文现在均不再是测试版。请参见此主题帖，了解我们在预排期推文发布后对其做出的更改。这包括为预排期推文生成 HTML 预览的功能。

v2

广告 API 第 2 版于 2017 年 7 月 10 日发布。广告 API 第 1 版的生命周期于 2018 年 1 月 10 日结束。