> ## 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.

# X API

> 使用 X API 发布内容的选项

## X BYO API 密钥

<Info>
  自 2026 年 3 月 31 日起，所有 X/Twitter 操作都需要你自己的 API 凭据。在通过 OAuth 关联你的 X 账户后，请在每次针对 X 的请求中包含这 2 个 header：

  | Header                        | 值                                  |
  | ----------------------------- | ---------------------------------- |
  | `X-Twitter-OAuth1-Api-Key`    | 你的 API Key（Consumer Key）           |
  | `X-Twitter-OAuth1-Api-Secret` | 你的 API Key Secret（Consumer Secret） |

  尚未关联？请参见 [X BYO Key 设置指南](/dashboard/connect-social-accounts/x-twitter-byo-keys) 以连接你的 X 账户。
</Info>

<Note>
  Ayrshare 不再对 X/Twitter 施加自己的每月或每日速率限制。由于 X 请求使用
  你自己的凭据（BYO），你的使用完全由你自己的 X Developer 应用限制来管理。详情请参见
  [X API 速率限制
  文档](https://developer.x.com/en/docs/x-api/rate-limits)。
</Note>

## 发布到 X (Twitter)

使用 X API（原 Twitter API）发布带有链接和图片的基本帖子的 JSON：

```json X Post theme={"system"}
{
  "post": "The best Tweet ever #best https://www.twitter.com", // empty string is allowed
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["twitter"]
}
```

<ul class="custom-bullets">
  <li>
    除非推文中包含图片或视频，否则 X 将自动预览推文中的链接。
    在上面的示例中会显示图片。移除图片后，链接预览将会
    显示。
  </li>

  <li>
    如果你的视频不是以已知的视频扩展名（如 mp4）结尾，请使用 `isVideo`
    参数。详情请参见 [/post 端点](/apis/post/post)。
  </li>

  <li>
    X 还支持发送无帖子文本的媒体。如果你不希望包含帖子文本，
    请发送空字符串 `post: ""`。
  </li>

  <li>
    你可以在单条推文中上传最多 4 张图片或视频。请参见 [发布 Twitter
    视频](/media-guidelines/x_twitter) 的重要指南和限制。
  </li>

  <li>
    更多信息请参见 [X 媒体指南](/media-guidelines/x_twitter) 和 [X
    授权](/dashboard/connect-social-accounts/x-twitter)。
  </li>
</ul>

## X 选项

你可以使用 `twitterOptions` 参数为帖子设置额外选项。

```json X Options theme={"system"}
{
  "twitterOptions": {
    "altText": ["This is my best pic", "😃 here is the next one"],
    "blockCountries": ["US", "CA"], // or "allowCountries": ["GB", "IE"]
    "longPost": true,
    "longVideo": true,
    "poll": {
      "duration": 5, // required. Number in minutes
      "options": ["yes", "maybe", "no"] // required
    },
    "quoteTweetId": "651601430669664256",
    "replySettings": "mentioned",
    "subscribersOnly": true,
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg",

    // Video Metadata
    "videoTitle": "My Product Demo",
    "videoDescription": "A short walkthrough of our latest release.",

    // Subtitles / Captions for Videos
    "subTitleUrl": "https://img.ayrshare.com/012/captions.srt",
    "subTitleLanguage": "en",
    "subTitleName": "English",

    // Thread Options
    "thread": true,
    "threadNumber": true,
    "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  }
}
```

X 选项是可选字段，可用于控制帖子。

<ParamField body="altText" type="array of strings">
  用于无障碍和屏幕阅读器的图片替代文本。每条替代文本最多 1,000 个字符。

  更多信息请参见 [替代文本](/apis/post/social-networks/x-twitter#alt-text)。
</ParamField>

<ParamField body="blockCountries" type="array of strings">
  通过阻止某些区域将媒体限制到特定国家/地区。使用 [国家/地区代码](/iso-codes/country)。

  不能与 `allowCountries` 同时使用。更多信息请参见 [地理限制](/apis/post/social-networks/x-twitter#geo-restrictions)。
</ParamField>

<ParamField body="allowCountries" type="array of strings">
  通过允许某些区域将媒体限制到特定国家/地区。使用 [国家/地区代码](/iso-codes/country)。

  不能与 `blockCountries` 同时使用。更多信息请参见 [地理限制](/apis/post/social-networks/x-twitter#geo-restrictions)。
</ParamField>

<ParamField body="longPost" type="boolean" default={false}>
  为 Premium 用户启用长达 25,000 个字符的长帖子。

  更多信息请参见 [长帖子](/apis/post/social-networks/x-twitter#long-post)。
</ParamField>

<ParamField body="longVideo" type="boolean" default={false}>
  允许经过批准的账户发布超过 2 分 20 秒的视频。

  更多信息请参见 [长视频](/apis/post/social-networks/x-twitter#long-video)。
</ParamField>

<ParamField body="poll" type="object">
  使用自定义选项和持续时间进行投票。

  必填字段：`duration`（分钟数）、`options`（字符串数组）。

  更多信息请参见 [投票](/apis/post/social-networks/x-twitter#polls)。
</ParamField>

<ParamField body="quoteTweetId" type="string">
  通过指定推文 ID 引用另一条推文。

  更多信息请参见 [引用推文](/apis/post/social-networks/x-twitter#quote-tweet)。
</ParamField>

<ParamField body="replySettings" type="string">
  控制谁可以回复帖子。

  值：`following`、`mentioned`、`subscribers` 或 `verified`。

  更多信息请参见 [回复设置](/apis/post/social-networks/x-twitter#reply-settings)。
</ParamField>

<ParamField body="subscribersOnly" type="boolean" default={false}>
  仅使帖子对订阅者可见。

  更多信息请参见 [仅订阅者](/apis/post/social-networks/x-twitter#subscribers-only)。
</ParamField>

<ParamField body="subTitleUrl" type="string">
  使用 SRT 文件为视频添加字幕/说明。必须是以 `.srt` 结尾的有效 SRT 文件 URL。

  更多信息请参见 [视频字幕/说明](/apis/post/social-networks/x-twitter#subtitles-captions-for-videos)。
</ParamField>

<ParamField body="subTitleLanguage" type="string" default="en">
  字幕的语言。必须是有效的 [语言代码](/iso-codes/language)。
</ParamField>

<ParamField body="subTitleName" type="string">
  字幕轨道的名称。最多 150 个字符。
</ParamField>

<ParamField body="thumbNail" type="string">
  为视频设置缩略图（封面图）。必须是 JPEG、PNG、BMP 或 WebP 图片文件的 URL。

  更多信息请参见 [视频缩略图](/apis/post/social-networks/x-twitter#video-thumbnail) 和图片要求 [X 媒体指南](/media-guidelines/x_twitter#video-thumbnail)。
</ParamField>

<ParamField body="videoTitle" type="string">
  设置视频的标题。映射到 X Media Studio 中的标题字段。

  更多信息请参见 [视频元数据](/apis/post/social-networks/x-twitter#video-metadata)。
</ParamField>

<ParamField body="videoDescription" type="string">
  设置视频的描述。映射到 X Media Studio 中的描述字段。

  更多信息请参见 [视频元数据](/apis/post/social-networks/x-twitter#video-metadata)。
</ParamField>

<ParamField body="thread" type="boolean" default={false}>
  将长帖子分成连接的线程系列，可选择编号和媒体。

  更多信息请参见 [线程](/apis/post/social-networks/x-twitter#thread)。
</ParamField>

<ParamField body="threadNumber" type="boolean" default={false}>
  自动以 1/n 格式在线程末尾添加编号。

  需要 `thread: true`。
</ParamField>

<ParamField body="mediaUrls" type="array of strings">
  将媒体对象添加到线程。每个媒体对象将按顺序添加到每个线程。

  使用 `null` 跳过特定线程的媒体。使用具有多个 URL 的对象为每个线程添加多个媒体。
</ParamField>

## 替代文本

为推文的图片添加替代文本（也称为 alt text）。X 替代文本是一项无障碍功能，用于提供附加的用户信息并支持屏幕阅读器。

在 `twitterOptions` 对象中使用 `altText`。

```json X Alt Text theme={"system"}
{
  "twitterOptions": {
    "altText": ["This is my best pic", "😃 here is the next one"] // Array of Alt Texts
  }
}
```

每条替代文本必须对应 `mediaUrls` 数组中的一张图片。替代文本将按顺序应用于每张图片。

<Note>
  替代文本不能应用于视频。如果 `mediaUrls` 中包含带有 `altText` 的视频，
  该视频将不会发布。替代文本必须为 1,000 个字符或更少。
</Note>

## 地理限制

你可以通过将 `blockCountries` 和 `allowCountries` 参数与 [国家/地区代码](/iso-codes/country) 结合使用，将 X 媒体（例如图片或视频）限制到特定国家/地区。
帖子仍将在所有国家/地区显示，但媒体将在指定国家/地区不可用。

<CodeGroup>
  ```json Block Countries theme={"system"}
  {
    "twitterOptions": {
      "blockCountries": ["US", "CA"]
    }
  }
  ```

  ```json Allow Countries theme={"system"}
  {
    "twitterOptions": {
      "allowCountries": ["GB", "IE"]
    }
  }
  ```
</CodeGroup>

<ul class="custom-bullets">
  <li>
    `blockCountries`：要阻止的国家/地区代码数组。参见 [国家/地区代码](/iso-codes/country)。
  </li>

  <li>
    `allowCountries`：允许的国家/地区代码数组。参见 [国家/地区代码](/iso-codes/country)。
  </li>
</ul>

你一次只能使用 `blockCountries` 或 `allowCountries` 中的一个参数。
如果同时使用两个参数或某个国家/地区不受 X 支持，地理限制将被忽略。

## 长帖子

拥有 Premium X 账户（如 Premium 或 Premium Plus）的用户，能够发布最长 25,000 个字符的长帖子。Ayrshare 会自动允许 Premium X 账户用户发布长帖子。

如果用户更改了他们的 X Premium 状态，请等待 24 小时以在 Ayrshare 中反映。你可以使用 [/user](/apis/user/overview) 或 [/analytics](/apis/analytics/social) 端点检查用户的 Premium 订阅状态。

你还可以通过 `longPost` body 参数强制接受长格式帖子。可以通过在请求中包含以下 JSON 来完成：

```json X Long Post theme={"system"}
{
  "twitterOptions": {
    "longPost": true
  }
}
```

但是，如果没有 Premium 账户的用户尝试发布长推文，系统将返回 `code: 111` 错误。

## 长视频

*需要 Business 或 Enterprise 计划。*

X 要求视频的 [最大视频长度](/media-guidelines/x_twitter#video) 为 2 分 20 秒。
但是，如果你已获得 X 的批准上传较长的视频，例如用户的 X 账户为 Premium 账户或在 [Amplify Partner 计划](https://media.twitter.com/en/articles/products/2018/in-stream-video-ads-for-publishers) 中，你可以发布长达 10+ 分钟的视频。

<Warning>
  在使用 `longVideo` 参数之前，请验证你的用户的 X 账户是 Premium 或在 [Amplify Partner
  计划](https://media.twitter.com/en/articles/products/2018/in-stream-video-ads-for-publishers) 中
  。如果你的用户的 X 账户未获授权发布长视频
  ，系统将返回错误。
</Warning>

发布长视频时使用 `longVideo` twitterOptions 参数：

```json X Long Video theme={"system"}
{
  "twitterOptions": {
    "longVideo": true
  }
}
```

## 提及

通过在帖子文本中添加 `@handle` 来提及其他 X 用户。例如：

```json X Mention theme={"system"}
{
  "post": "The best social media API @Ayrshare ever!",
  "platforms": ["twitter"]
}
```

<Warning>
  请查看提及功能的[重要规则](/testing/post-verification#mentions)。
</Warning>

## 投票

使用 `twitterOptions` 的 `poll` 参数进行 X 投票。

```json X Poll theme={"system"}
{
  "twitterOptions": {
    "poll": {
      "duration": 5, // required. Number in minutes
      "options": ["yes", "maybe", "no"] // required
    }
  }
}
```

<ul class="custom-bullets">
  <li>`duration`：指定投票持续时间的分钟数。</li>
  <li>`options`：投票选项的字符串数组。</li>
</ul>

## 引用推文

你可以通过指定底层推文 ID 引用另一条推文。ID 可以通过 [`/post`](/apis/post/post) 响应中的 `postIds` 字段、[获取历史](/apis/history/get-history) 或直接从推文 URL 检索：[https://twitter.com/Ayrshare/status/**1651601430669664256**](https://twitter.com/Ayrshare/status/1651601430669664256)

```json X Quote Tweet theme={"system"}
{
  "twitterOptions": {
    "quoteTweetId": "651601430669664256" // low-level Tweet Id
  }
}
```

## 回复设置

你可以为帖子设置回复设置，仅允许某些类型的用户回复。

```json X Reply Settings theme={"system"}
{
  "twitterOptions": {
    "replySettings": "mentioned"
  }
}
```

`replySettings` 参数可以是以下值之一：

<ul class="custom-bullets">
  <li>`following`：仅 X 账户关注的用户可以回复。</li>
  <li>`mentioned`：仅在帖子中被提及的用户可以回复。</li>

  <li>
    `subscribers`：仅发布帖子的 X 账户的订阅者可以回复。
  </li>

  <li>`verified`：仅在 X 上经过验证的用户可以回复帖子。</li>
</ul>

## 仅订阅者

你可以使用 `subscribersOnly` 参数将帖子设置为仅对订阅者可见。

```json X Subscribers Only theme={"system"}
{
  "twitterOptions": {
    "subscribersOnly": true
  }
}
```

## 视频字幕/说明

你可以通过包含 [SRT 文件](https://en.wikipedia.org/wiki/SubRip) 为视频添加 X 字幕（也称为 X 说明）。在 `twitterOptions` 对象中使用 `subTitleUrl` 字段指定 SRT 文件的 URL。

```json X Subtitles theme={"system"}
{
  "twitterOptions": {
    "subTitleUrl": "https://img.ayrshare.com/012/captions.srt",
    "subTitleLanguage": "en",
    "subTitleName": "English"
  }
}
```

<ul class="custom-bullets">
  <li>
    `subTitleUrl`：有效的 SRT 文件。URL 必须以 `https://` 开头，以 `.srt` 结尾，并且是
    有效的 SRT 文件。
  </li>

  <li>
    `subTitleLanguage`：可选：字幕的语言。必须是有效的 [语言
    代码](/iso-codes/language)。默认："en"。
  </li>

  <li>
    `subTitleName`：可选：字幕轨道的名称。该名称旨在
    在播放期间作为选项对用户可见。支持的最大名称长度为 150 个字符。
    默认："English"。
  </li>
</ul>

## 视频缩略图

为 Twitter/X 视频设置缩略图（封面图）。缩略图在视频播放前显示，帮助用户理解视频内容。在 `twitterOptions` 对象中使用 `thumbNail`。

```json Twitter/X Video Thumbnail theme={"system"}
{
  "twitterOptions": {
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg"
  }
}
```

<ul class="custom-bullets">
  <li>
    "thumbNail"：缩略图图片的 URL。支持的图片格式是 JPEG、PNG、BMP 和 WebP。
  </li>

  <li>
    缩略图应该代表视频内容，并且具有视觉吸引力以鼓励互动。
  </li>

  <li>
    图片要求请参见 [X 媒体指南](/media-guidelines/x_twitter#video-thumbnail)。
  </li>
</ul>

## 视频元数据

为发布到 X 的视频设置标题和描述。这些映射到 X Media Studio 中的标题和描述字段。在 `twitterOptions` 对象中使用 `videoTitle` 和 `videoDescription` 字段。

```json X Video Metadata theme={"system"}
{
  "twitterOptions": {
    "videoTitle": "My Product Demo",
    "videoDescription": "A short walkthrough of our latest release."
  }
}
```

<ul class="custom-bullets">
  <li>`videoTitle`：视频的标题，映射到 X Media Studio 的标题字段。</li>

  <li>
    `videoDescription`：视频的描述，映射到 X Media Studio 的描述
    字段。
  </li>
</ul>

## 视频变现 (Pro Media)

Ayrshare 支持通过 X 的 Pro Media 计划为符合条件的账户提供 X (Twitter) 视频变现。这是一项受限的功能 — 如果你想获得访问权限，请 [联系我们](mailto:support@ayrshare.com)。

## 线程

X 线程（也称为 tweetstorm）是 X（前 Twitter）上一系列相连的帖子，可以让你分享超出单个帖子字符限制的更长想法，一起查看时呈现为一个连续的叙述。

<img src="https://mintcdn.com/ayrshare-docs/Nmrhj2Gh7WSf62Bh/images/apis/post/x-thread.webp?fit=max&auto=format&n=Nmrhj2Gh7WSf62Bh&q=85&s=35bd3fbb8c2c1af6a4b3d96b8dae54d8" width="70%" class="center" alt="X Thread" data-path="images/apis/post/x-thread.webp" />

### 发布线程

X 线程可以通过 API 发布。
线程是一个被分成一组回复线程的帖子，并在 X 中用一条线关联。
你可以自动拆分帖子，也可以在帖子文本中指定 [线程分隔符](/apis/post/social-networks/x-twitter#thread-breaks)。

```json X Thread theme={"system"}
{
    "twitterOptions": {
        "thread": true,        // required for TweetStorm
        "threadNumber": true,  // optional to add numbers to each thread
        "mediaUrls": ["https://site.com/image1.png", "https://site.com/image2.png", ...]  // optional one media object is added to a thread in order
    }
}
```

<ul class="custom-bullets">
  <li>
    `thread: true` 根据换行自动将帖子文本拆分为多个线程。
  </li>

  <li>
    `threadNumber: true` 自动以 1/n 格式在线程末尾添加编号。
    例如，5 个线程中的第 2 个将追加：2/5
  </li>

  <li>
    `mediaUrls: [array of urls]` 按顺序将每个媒体对象（图片或视频）添加到线程。
    每个线程仅按顺序添加一个媒体对象。
  </li>
</ul>

如果帖子作为 X 线程发送，返回的帖子分析将是推文的数组，`"twitter": []`。更多信息请参见 [帖子分析 200 响应](/apis/analytics/post)。

#### 线程媒体

##### 跳过媒体

通过在数组中使用 `null` 跳过线程的媒体。例如：

`["https://site.com/image1.png", null, "https://site.com/image2.png"]`

这会将 image1 放在第一条推文上，第二条推文没有图片，image2 放在第三条推文上。

##### 多个媒体

通过在 `mediaUrls` 数组中添加带有媒体 URL 的对象 `{}`，可以为线程中的推文添加多个媒体对象。可以使用任何唯一的对象键。例如：

```json X Thread with Multiple Media URLs theme={"system"}
{
  "twitterOptions": {
    "thread": true,
    "threadNumber": true,
    "mediaUrls": [
      "https://img.ayrshare.com/random/photo-1.jpg",
      {
        "1": "https://img.ayrshare.com/random/photo-2.jpg",
        "2": "https://img.ayrshare.com/random/photo-3.jpg"
      },
      "https://img.ayrshare.com/random/photo-4.jpg"
    ]
  }
}
```

在此示例中，第一条推文将包含 photo-1.jpg，第二条推文包含 photo-2.jpg 和 photo-3.jpg，第三条推文包含 photo-4.jpg。

#### 线程分隔符

Ayrshare 会自动将帖子文本拆分为适合推文长度（> 280 个字符）的推文。
在创建线程时，我们优先考虑在可能的情况下将完整句子保留在一个帖子中。
如果一个句子放不下，我们会在句子之间拆分。
对于非常长的句子，我们会在单词之间拆分。
在单词过长的极少情况下，我们会拆分单词本身。

你也可以手动向帖子文本添加 `\n\n` 段落分隔符，以指示应创建一个独立的线程。
如果帖子文本中有 `\n\n`，我们将不会自动将帖子拆分为线程。

例如：

```json Example X  Thread theme={"system"}
{
  "post": "This is tweet 1\n\nThis is tweet 2.",
  "platforms": ["twitter"],
  "twitterOptions": {
    "thread": true
  }
}
```

将生成线程中的两条推文。

如果你想添加段落但不拆分为多条推文，请使用 `\u2063\n\u2063\n`

```json X Thread with Paragraphs theme={"system"}
{
  "post": "This is paragraph 1\u2063\n\u2063\nThis is paragraph 2.",
  "platforms": ["twitter"],
  "twitterOptions": {
    "thread": true
  }
}
```

由于帖子少于 280 个字符，将生成一条包含两个段落的推文。

### 删除线程

要删除推文风暴，使用响应中返回的顶层帖子 ID 调用 [/post 删除端点](/apis/post/delete-post)。所有线程都将被删除。

## 字符限制

更多信息请参见 [X/Twitter 字符限制](/help-center/technical-support/character_limits#x%2Ftwitter-character-limits)。

## X 视频兼容性

某些视频软件创建的 MP4 文件与 X 不兼容。例如，早于 2019.0.9 的 Camtasia 版本创建的 MP4 文件被 X 拒绝。另外，多个音轨通常会导致问题。

如果你在发布时收到以下消息，则表明视频与 Twitter 不兼容，需要重新编码。

`"file is currently unsupported"`

请检查你的视频软件的兼容性。例如，Adobe Media Encoder 有 Twitter 1080p Full HD 的导出预设。

<img class="Adobe Media Encoder" src="https://mintcdn.com/ayrshare-docs/Nmrhj2Gh7WSf62Bh/images/apis/post/tw-video.webp?fit=max&auto=format&n=Nmrhj2Gh7WSf62Bh&q=85&s=71016a72242be3d17af4bee05aee915a" alt="Adobe Media Encoder" width="890" height="214" data-path="images/apis/post/tw-video.webp" />

有关 [更多 X API 示例](https://www.ayrshare.com/twitter-api-how-to-post-and-get-analytics-with-the-twitter-api#twitter-api-examples)，请参见此处。

## 仅订阅者

你可以使用 `subscribersOnly` 参数将帖子设置为仅对订阅者可见。

```json X Subscribers Only theme={"system"}
{
  "twitterOptions": {
    "subscribersOnly": true
  }
}
```

## 回复设置

你可以为帖子设置回复设置，仅允许某些类型的用户回复。

```json X Reply Settings theme={"system"}
{
  "twitterOptions": {
    "replySettings": "mentioned"
  }
}
```

`replySettings` 参数可以是以下值之一：

<ul class="custom-bullets">
  <li>`following`：仅 X 账户关注的用户可以回复。</li>
  <li>`mentioned`：仅在帖子中被提及的用户可以回复。</li>

  <li>
    `subscribers`：仅发布帖子的 X 账户的订阅者可以回复。
  </li>

  <li>`verified`：仅在 X 上经过验证的用户可以回复帖子。</li>
</ul>