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

<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 App 限制決定。詳情請參閱
  [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 影片的重要規範
    與限制請參閱 [發布 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">
  圖片的替代文字（alt text），可協助無障礙功能與螢幕閱讀器讀取內容。每段 alt text 最多 1,000 個字元。

  更多資訊請參閱 [Alt Text](/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">
  透過指定 Tweet 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 中的 title 欄位。

  更多資訊請參閱 [影片中繼資料](/apis/post/social-networks/x-twitter#video-metadata)。
</ParamField>

<ParamField body="videoDescription" type="string">
  設定影片的描述。會對應到 X Media Studio 中的 description 欄位。

  更多資訊請參閱 [影片中繼資料](/apis/post/social-networks/x-twitter#video-metadata)。
</ParamField>

<ParamField body="thread" type="boolean" default={false}>
  將長貼文拆成一系列連貫的 thread，並可選擇加入編號與媒體。

  更多資訊請參閱 [Threads](/apis/post/social-networks/x-twitter#thread)。
</ParamField>

<ParamField body="threadNumber" type="boolean" default={false}>
  自動在每則 thread 末尾以 1/n 格式加上編號。

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

<ParamField body="mediaUrls" type="array of strings">
  為 thread 系列的每則貼文加入媒體物件。每則 thread 會依序加上一個媒體物件。

  若要跳過某則 thread 的媒體，請使用 `null`。若要為單一 thread 加入多個媒體，請使用包含多個 URL 的物件。
</ParamField>

## Alt Text

為推文的圖片加上替代文字（alt text）。X alt text 是一項無障礙功能，可提供額外的使用者資訊，並協助螢幕閱讀器讀取內容。

請在 `twitterOptions` 物件中使用 `altText`。

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

每個 alt text 必須對應到 `mediaUrls` 陣列中的一張圖片，並依序套用到每張圖片上。

<Note>
  Alt text 無法套用到影片。若 `mediaUrls` 中含有影片並附上 `altText`，
  該影片將不會發布。Alt text 必須為 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 Plan。*

X 要求影片的 [最長長度](/media-guidelines/x_twitter#video) 為 2 分 20 秒。
不過，若你的使用者已被 X 核准可上傳更長的影片（例如使用者的 X 帳號為 Premium 帳號，或加入 [Amplify Partner Program](https://media.twitter.com/en/articles/products/2018/in-stream-video-ads-for-publishers)），就可以發布長達 10 分鐘以上的影片。

<Warning>
  在使用 `longVideo` 參數前，請確認你的使用者的 X 帳號為 Premium 或已加入 [Amplify Partner
  Program](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>

## 引用推文

你可以透過指定底層的 Tweet 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 captions）。使用 `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 中的 title 與 description 欄位。請在 `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 的 title 欄位。</li>

  <li>
    `videoDescription`：影片描述，對應到 X Media Studio 的 description
    欄位。
  </li>
</ul>

## 影片營利（Pro Media）

Ayrshare 透過 X 的 Pro Media 計畫，為符合資格的帳號提供 X（Twitter）影片營利支援。此為受限功能 — 若你希望取得存取權限，請[與我們聯絡](mailto:support@ayrshare.com)。

## Thread

X Thread（又稱為 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" />

### 發布 Thread

X Thread 可以透過 API 發布。
Thread 是被拆分成多則回覆並在 X 上以一條線串接的貼文。
你可以讓系統自動拆分貼文，或在貼文文字中指定 [thread 分隔](/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`：依換行符號自動將貼文文字拆分成多則 thread。
  </li>

  <li>
    `threadNumber: true`：自動在每則 thread 末尾以 1/n 格式加上編號。
    例如，第 2 則（共 5 則）thread 末尾會附加 2/5。
  </li>

  <li>
    `mediaUrls: [array of urls]`：依序將每個媒體物件（圖片或影片）加到對應的 thread 上。
    每則 thread 依序只會加上一個媒體物件。
  </li>
</ul>

若貼文以 X Thread 發送，回傳的貼文分析會是一個推文陣列 `"twitter": []`。詳情請參閱 [Post Analytics 200 Response](/apis/analytics/post)。

#### Thread 媒體

##### 跳過媒體

在陣列中使用 `null` 即可跳過某則 thread 的媒體。例如：

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

這會將 image1 放在第一則推文、第二則推文無圖片，image2 放在第三則推文。

##### 多個媒體

在 `mediaUrls` 陣列中加入包含多個媒體 URL 的物件 `{}`，即可為 Thread 中的單一推文加入多個媒體物件。可使用任何唯一的物件 key。例如：

```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。

#### Thread 分隔

Ayrshare 會自動將貼文文字拆分成適合的推文長度（超過 280 個字元）。
在建立 thread 時，我們會盡可能將完整的句子保留在同一則貼文中。
如果單一句子放不下，就會在句子之間分隔；
若句子非常長，就會在字詞之間分隔；
極少數情況下，如果單一字詞過長，我們才會將該字詞本身拆開。

你也可以在貼文文字中手動加入段落 `\n\n` 來指定要建立一則新的 thread。
如果貼文文字中含有 `\n\n`，我們就不會再自動將貼文拆分成 thread。

例如：

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

會在該 thread 中產生兩則推文。

若你想加入段落但不拆成不同的推文，請使用 `\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 個字元，因此會產生單一推文並包含兩個段落。

### 刪除 Thread

若要刪除 Tweet Storm，請呼叫 [/post 刪除端點](/apis/post/delete-post) 並傳入回應中最上層的貼文 ID。所有 thread 都會被一併刪除。

## 字元限制

更多資訊請參閱 [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>