> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 即将到来的 API 变更

> 可能会影响你集成的 API 变更

以下 API 变更将在指定日期生效。
请仔细审阅其中可能存在的破坏性变更。
所有新特性请见 [What's New](/whatsnew/latest)。

<Update label="2026 年 6 月 15 日">
  <ul class="custom-bullets">
    <li>
      **Facebook：Meta 停用了独立展示（reach）与 3 秒视频观看的 Insights 指标。** Meta 已在所有 Graph API 版本中移除这些指标，因此受影响的字段不再返回。详情请参见 [Meta Graph API v25 changelog](https://developers.facebook.com/blog/post/2026/02/18/introducing-graph-api-v25-and-marketing-api-v25/)。

      <ul class="custom-bullets">
        <li>
          [GET analytics/post](/apis/analytics/post) 不再返回以下 Facebook 字段：

          <ul class="custom-bullets">
            <li>impressionsUnique → 迁移到 `mediaView`</li>
            <li>impressionsFanUnique → 迁移到 `mediaView`</li>
            <li>impressionsOrganicUnique → 迁移到 `mediaView`</li>
            <li>impressionsPaidUnique → 迁移到 `mediaViewIsFromAds`</li>
            <li>videoViewsUnique → 使用 `videoViews` 获取非唯一 3 秒观看数</li>
            <li>`totalVideoViews*Unique` 和 `totalVideoImpressions*` 系列字段（例如 `totalVideoViewsOrganicUnique`、`totalVideoViewsPaidUnique`、`totalVideoViewsUnique`）</li>
          </ul>
        </li>

        <li>
          [GET analytics/social](/apis/analytics/social) 不再返回以下 Facebook 字段：

          <ul class="custom-bullets">
            <li>`pagePostsImpressions*` 系列（`pagePostsImpressions`、`pagePostsImpressionsPaid`、`pagePostsImpressionsUnique`、`pagePostsImpressionsOrganicUnique`、`pagePostsImpressionsViral*`、`pagePostsImpressionsNonviral*`）→ 迁移到 `pageMediaView`</li>
            <li>pagePostsServedImpressionsOrganicUnique → 迁移到 `pageMediaView`</li>
            <li>pageVideoViewsUnique → 使用 `pageVideoViews` 获取非唯一 3 秒观看数</li>
          </ul>
        </li>

        <li>
          使用 `mediaView` / `pageMediaView` 表示 reach。计划推出一个 Total Unique Media Views 后续指标。诸如 `reactionsByType`、`videoViews`、`mediaView`、`pagePostEngagements`、`pageVideoViews` 和 `pageVideoViewsPaid` 等仍支持的字段不受影响。
        </li>
      </ul>
    </li>
  </ul>
</Update>

<Update label="2026 年 5 月 11 日">
  <ul class="custom-bullets">
    <li>
      **YouTube 瞬时错误现在返回 HTTP 503/504 而非 500：** 一些先前以 HTTP 500（`code: 176`）返回的 YouTube 上传失败，现在会返回 HTTP 503（`code: 454`）或 HTTP 504（`code: 453`）。两种响应都会包含 `retryAvailable: true`。原本通过筛选 HTTP 500 来重试 YouTube 上传的客户集成，应改为根据响应体中的 `retryAvailable` 字段进行筛选。详情请参见[错误码](/errors/errors-ayrshare)。
    </li>
  </ul>
</Update>

<Update label="2026 年 4 月 9 日">
  <ul class="custom-bullets">
    <li>
      **空分析返回错误 187：** 请求 [社交分析](/apis/analytics/social) 或 [帖子分析](/apis/analytics/post) 时，如果没有平台返回数据，现在会返回 `{ "status": "error", "code": 187 }`，而不是 `{ "status": "success" }`。请更新依赖之前 “空数据成功” 行为的客户端代码。
    </li>
  </ul>
</Update>

<Update label="2026 年 3 月 31 日">
  <ul class="custom-bullets">
    <li>
      **X/Twitter BYO Key 要求：** 通过 Ayrshare 进行的所有 X/Twitter 操作都将要求使用你自己的 API 凭据。在通过 OAuth 关联 X 账户后，请在每次 X/Twitter 请求中包含 2 个请求头：`X-Twitter-OAuth1-Api-Key` 和 `X-Twitter-OAuth1-Api-Secret`。缺少有效凭据的请求将被拒绝。搭建说明请参见 [X BYO Key 搭建指南](/dashboard/connect-social-accounts/x-twitter-byo-keys)。
    </li>

    <li>
      **RSS-to-X 停用：** 2026 年 3 月 31 日后，将不再支持通过 RSS 自动发布到 X/Twitter。RSS 订阅按计划运行、不携带每次请求的凭据，与 BYO Key 模型不兼容。其他所有平台的 RSS 自动发布不受影响。
    </li>

    <li>
      **X Account Activity Webhook 停用：** 2026 年 3 月 31 日后，X Account Activity webhook 动作（`accountActivity`）将不再可用。这包括对已关联 X 账户的所有实时事件通知（帖子、@ 提及、私信、点赞、关注、屏蔽等）。
    </li>
  </ul>
</Update>

<Update label="2025 年 11 月 14 日">
  <ul class="custom-bullets">
    <li>
      自 2025 年 11 月 14 日起，Facebook 将弃用 [GET analytics/social](/apis/analytics/social) 中的以下字段：

      <ul class="custom-bullets">
        <li>pageFans</li>
        <li>pageFansCity</li>
        <li>pageFansLocale</li>
        <li>pageFansCountry</li>
        <li>pageFansAdds</li>
        <li>pageFanAddsUnique</li>
        <li>pageFanRemoves</li>
        <li>pageFanRemovesUnique</li>
        <li>pageImpressions → 迁移到 `pageMediaView`</li>
        <li>pageImpressionsPaidUnique → 迁移到 `pageMediaViewIsFromAds`</li>
        <li>pageImpressionsUnique</li>
        <li>pageImpressionsViral</li>
        <li>pageImpressionsViralUnique</li>
        <li>pageImpressionsPaid → 迁移到 `pageMediaViewIsFromAds`</li>
      </ul>
    </li>

    <li>
      自 2025 年 11 月 14 日起，Facebook 将弃用 [GET analytics/post](/apis/analytics/post) 中的以下字段：

      <ul class="custom-bullets">
        <li>impressions 和 impressionsFanPaidUnique → 迁移到 `mediaView`。可以通过 `mediaViewIsFromAds`（广告归因的观看数）和 `mediaViewIsFromFollowers`（粉丝归因的观看数）获取更细粒度的拆分。</li>
        <li>postImpressionsUnique（Reels）→ 使用 `blueReelsPlayCount` 获取 Reels 播放次数，或使用 `postVideoViewTime` 获取总观看时长。</li>
      </ul>
    </li>
  </ul>
</Update>

<Update label="2025 年 9 月 1 日">
  <ul class="custom-bullets">
    <li>
      自 2025 年 9 月 1 日起，Instagram 的 [get comments](/apis/comments/get-comments) 接口
      将不再在回复对象中包含 `text` 字段。请改用 `comment` 字段
      获取回复内容。
    </li>
  </ul>
</Update>

<Update label="2025 年 6 月 1 日">
  <ul class="custom-bullets">
    <li>
      X（Twitter）的 [get comments](/apis/comments/get-comments) 接口将把用户的公开
      指标移到新的 `publicMetrics` 对象中。以下字段将从顶层
      移入 `publicMetrics` 对象：

      <ul class="custom-bullets">
        <li>followersCount</li>
        <li>followingCount</li>
        <li>tweetCount</li>
        <li>listedCount</li>
        <li>mediaCount</li>
      </ul>
    </li>

    <li>
      Facebook 将弃用 [GET
      analytics/social](/apis/analytics/social) 中的以下字段：

      <ul class="custom-bullets">
        <li>pageVideoViews10S</li>
        <li>pageVideoViews10SAutoplayed</li>
        <li>pageVideoViews10SClickToPlay</li>
        <li>pageVideoViews10SOrganic</li>
        <li>pageVideoViews10SPaid</li>
        <li>pageVideoViews10SRepeat</li>
        <li>pageVideoViews10SUnique</li>
      </ul>
    </li>
  </ul>
</Update>

<Update label="2025 年 5 月 7 日">
  <ul class="custom-bullets">
    <li>
      YouTube 已弃用允许区域和屏蔽区域的设置。你仍然可以在
      post 接口中传入允许和屏蔽区域，但它们将被忽略。
    </li>
  </ul>
</Update>

<Update label="2025 年 4 月 20 日">
  <ul class="custom-bullets">
    <li>
      [Instagram 帖子分析](/apis/analytics/post) 的以下指标将被弃用：

      REELS：

      <ul class="custom-bullets">
        <li>
          playsCount
        </li>

        <li>
          clipsReplaysCount
        </li>

        <li>
          igReelsAggregatedAllPlaysCount
        </li>
      </ul>

      FEED/STORY：

      <ul class="custom-bullets">
        <li>
          impressionsCount
        </li>
      </ul>
    </li>

    <li>
      如果 `limit` 大于默认值 25，[history 接口](/apis/history/get-history) 将强制缓存 1 分钟。
    </li>
  </ul>
</Update>

<Update label="2025 年 3 月 1 日">
  TikTok 的 [get comments](/apis/comments/get-comments) 接口将统一字段命名，
  与其他社交网络保持一致。

  <ul class="custom-bullets">
    <li>
      字段 `replyList` 将重命名为 `replies`，`profileImage` 将重命名为
      `profileImageUrl`。
    </li>

    <li>两个新字段名已经可用，可在你的集成中直接使用。</li>

    <li>
      TikTok 有以下更新：

      <ul class="custom-bullets">
        <li>
          [社交分析](/apis/analytics/social) 接口：即将推出以下变更：
          `durationAverage` 字段将被弃用并移除；由于 TikTok API
          的限制，`shareCountTotal`、`viewCountTotal` 和 `commentCountTotal` 字段
          将只返回过去 60 天的合计值，而非全时段合计。若要立即使用
          60 天合计值，请在 API 请求体中添加 `period60Days: true`。注意：使用该
          参数将显著提升响应速度。
        </li>

        <li>
          [history platform](/apis/history/history-platform) 和 [post
          analytics](/apis/analytics/post) 接口：未在文档中列出的字段 `caption`、`comments`、
          `shares`、`likes`、`shareUrl` 和 `itemsId` 将被移除，请改用字段
          `post`、`commentsCount`、`sharesCount`、`likesCount`、`postUrl` 和 `id`。
        </li>
      </ul>
    </li>
  </ul>
</Update>

<Update label="2025 年 2 月 1 日">
  [/user](/apis/user/profile-details) 接口将改变其 API 用量的上报方式：

  <ul class="custom-bullets">
    <li>
      `monthlyApiCalls` 字段将扩展为统计所有 API 调用（发帖、评论、
      分析等）。
    </li>

    <li>如需仅统计发帖数量，请使用新字段 `monthlyPostCount`。</li>

    <li>
      `monthlyApiCallsQuota` 字段将被弃用，由新字段 `monthlyPostQuota`
      取代。
    </li>
  </ul>
</Update>

<Update label="2025 年 1 月 5 日">
  <ul class="custom-bullets">
    <li>
      Meta 正在弃用 Instagram [帖子分析
      接口](/apis/analytics/post) 上的 `videoViews` 字段。
    </li>

    <li>
      此外，Instagram [社交分析](/apis/analytics/social) 接口中的
      `emailContactsCount`、`getDirectionClicks`、`profileViewsCount`、
      `textMessageClicks`、`websiteClicksCount` 和 `phoneCallClicksCount` 字段将被移除。
    </li>

    <li>这些字段将在 2025 年 1 月 5 日移除。</li>
  </ul>
</Update>

<Update label="2024 年 12 月 15 日">
  <ul class="custom-bullets">
    <li>
      出于安全增强的考虑，我们将禁止把 Profile Key 当作 API Key 使用。如果你
      尝试用 Profile Key 代替 API Key，系统将返回错误。请[参见
      此处](/apis/overview#authorization)了解如何正确使用 Profile Key。
    </li>
  </ul>
</Update>

<Update label="2024 年 11 月 15 日">
  <ul class="custom-bullets">
    <li>
      我们更新了 TikTok 计划 webhook 错误的上报方式。这些错误现在会
      出现在 errors 数组中，与我们其他类型计划 webhook 的错误处理保持一致。
      请注意，当前顶层的错误仍会返回，但我们建议使用
      errors 数组。
    </li>

    <li>
      history 接口现在默认将响应作为对象返回。objResponse 参数会
      自动设为 true。
    </li>

    <li>
      Get All History LinkedIn 将为 mediaUrls 返回一个数组。之前如果只有一个媒体项，
      返回的是对象；有多个则返回数组。现在即使只有一个媒体项，也会始终
      返回数组。如果你需要之前的行为，可以使用查询参数 `objResponse: false`。
    </li>
  </ul>
</Update>

<Update label="2024 年 10 月 7 日">
  <ul class="custom-bullets">
    <li>
      media 接口将不再返回 url\_1080。如果你需要调整图片大小，请
      参见 [resize 接口](/apis/media/resize)。
    </li>
  </ul>
</Update>

<Update label="2024 年 9 月 16 日">
  <ul class="custom-bullets">
    <li>
      **2024 年 9 月 25 日更新**：Meta（Facebook）已经上线字段的弃用，因此
      字段的移除已生效。请参见[社交
      分析](/apis/analytics/social)中更新后的返回。
    </li>

    <li>
      Facebook 将[弃用若干
      字段](https://developers.facebook.com/docs/pages-api/changelog/)。2024 年 9 月 16 日之后，[社交分析
      接口](/apis/analytics/social-by-id) 将不再返回这些字段。
    </li>
  </ul>
</Update>

<Update label="2024 年 6 月 3 日">
  <ul class="custom-bullets">
    <li>
      [新的链接短链](/apis/links/overview) 系统将替代此前的短链接口，该接口已
      被 Google 弃用。新的链接短链需要附加功能 [Max
      Pack](/additional/maxpack)。
    </li>

    <li>
      链接短链默认关闭（`false`）。要在发帖时自动缩短链接，请在
      post 接口调用中使用 `shortenLinks: true`，其底层会使用新的 [link
      接口](/apis/links/overview)。
    </li>
  </ul>
</Update>

<Update label="2024 年 4 月 22 日">
  <ul class="custom-bullets">
    <li>
      Meta 将弃用其 Facebook Groups API。请参见
      [公告](https://www.ayrshare.com/blog/facebook-removes-groups-api-access-impact-and-implications/)。
    </li>
  </ul>
</Update>

<Update label="2024 年 4 月 16 日">
  <ul class="custom-bullets">
    <li>
      Instagram 已经明确了 online followers 数据集的时间范围。详情请
      参见[此处](/apis/analytics/instagram-follower-count)。
    </li>
  </ul>
</Update>

<Update label="2024 年 4 月 1 日">
  <ul class="custom-bullets">
    <li>
      [使用评论 ID 回复评论](/apis/comments/reply-to-comment) 的默认响应将
      按文档所列返回对象，而不是数组。如需保留数组响应，可以使用
      设为布尔值 `false` 的 objResponse 参数。
    </li>
  </ul>
</Update>

<Update label="2024 年 1 月 25 日">
  <ul class="custom-bullets">
    <li>
      [retry post 接口](/apis/post/retry-post) 将返回状态 "pending" 而非
      "success"，以更好地反映重试的状态。
    </li>

    <li>
      [scheduleDate 与 createDate 的 API 变更](/whatsnew/upcoming-api-changes#changes-in-effect-june-17-2022) 将发布。
    </li>
  </ul>
</Update>

<Update label="2023 年 12 月 8 日">
  <ul class="custom-bullets">
    <li>
      `/history/instagram` 接口的字段 `caption`、`message`、`createdTime` 和 `timestamp`
      已于 2023 年 4 月 1 日被弃用，即将被移除。请改用 `post` 和
      `created` 字段。
    </li>

    <li>
      `/history/linkedin` 接口的 `mediaUrls` 字段将以数组而非对象返回，以支持
      多张图片。你现在可以通过附加 LinkedIn 查询参数
      `?multiMedia=true` 强制返回数组。请注意，在 2023 年 12 月 1 日之前，必须使用
      `multiMedia` 查询参数才能返回含多张图片的媒体；2023 年 12 月 1 日之后，
      多张图片将默认返回。
    </li>

    <li>
      Scheduled Action TikTok webhook 中的字符串 `platform` 将被弃用。请像其他
      Scheduled Action webhook 一样使用 `platforms` 数组字段。
    </li>

    <li>删除评论文档已更正，以对齐正确的返回结构。</li>

    <li>
      TikTok 的 commentId 字段将由 id 字段替代，以对齐标准
      评论删除格式。
    </li>

    <li>
      Twitter 删除评论的返回将不再包含 `posts` 数组，以便与标准
      评论删除格式一致。新返回如下：
    </li>
  </ul>
</Update>

<Update label="2023 年 10 月 18 日">
  <ul class="custom-bullets">
    <li>
      [社交分析接口](/apis/analytics/social) 中以下 YouTube 字段将以
      数值而非字符串返回。
    </li>
  </ul>
</Update>

<Update label="2023 年 5 月 30 日">
  <ul class="custom-bullets">
    <li>
      我们已升级到 Twitter 的新 API v2。Twitter 在 v2 中弃用了若干字段，
      这将影响 /analytics/social 和 getAllHistory 接口。以下字段
      在 2023 年 9 月 1 日之前仍会返回，但值为零或空字符串。
    </li>
  </ul>
</Update>

<Update label="2023 年 5 月 8 日">
  <ul class="custom-bullets">
    <li>
      我们很高兴推出 [TikTok 直接发布](/apis/post/social-networks/tiktok)、评论
      管理和高级分析。你的用户将不再需要打开 TikTok 移动应用来发布并输入 caption 文本。
      现在通过 Ayrshare 发送后，TikTok 视频和 caption 会
      直接发布。
    </li>

    <li>
      我们同时也引入了 TikTok 评论的添加、获取和删除功能，以及人口统计
      分析数据。
    </li>

    <li>
      用户需要解绑并重新绑定其 TikTok 账户，以启用直接发布。
      现有连接将继续使用间接方式，需要 TikTok 移动应用完成发布。
    </li>
  </ul>
</Update>

<Update label="2023 年 2 月 17 日">
  <ul class="custom-bullets">
    <li>
      Google Business Profile 已更改可用的社交分析数据。新的
      可用字段如下。原有字段仍会存在，但值为零，并将
      于 2023 年 3 月 17 日完全移除。
    </li>
  </ul>
</Update>

<Update label="2022 年 10 月 1 日">
  <ul class="custom-bullets">
    <li>Get All Posts 的 descriptions、text、message 字段已统一为 `post` 字段。</li>
  </ul>
</Update>

<Update label="2022 年 9 月 12 日">
  <ul class="custom-bullets">
    <li>TikTok 字段已弃用：`shareUrl`，请改用 `postUrl`。</li>
  </ul>
</Update>

<Update label="2022 年 6 月 17 日">
  <ul class="custom-bullets">
    <li>
      对于所有 history 接口，字段 `createdAt`、`createdTime` 和 `timestamp` 将被
      `created` 字段替代，该字段以 UTC 格式返回创建时间。
    </li>

    <li>
      `scheduleDate` 字段将不再返回对象，而是返回一个包含 UTC 格式排期
      时间的字符串。
    </li>

    <li>
      /history 上未在文档中列出的 `created_date` 字段将被移除。请改用 `created`。
    </li>
  </ul>
</Update>

<Update label="2022 年 4 月 22 日">
  <ul class="custom-bullets">
    <li>
      对 [Facebook 帖子](/apis/analytics/post) 的分析将以以下格式将
      `reactions` 作为对象返回。
    </li>
  </ul>
</Update>

<Update label="2022 年 4 月 1 日">
  <ul class="custom-bullets">
    <li>
      History 默认返回最近的 20 条帖子。通过 `lastRecords` 参数最多可返回
      500 条。
    </li>
  </ul>
</Update>