X API

X BYO API Keys

自 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 設定指南來連結你的 X 帳號。

Ayrshare 不再對 X/Twitter 施加自身的月度或每日速率限制。由於 X 請求使用你自己的憑證（BYO），你的使用量僅由你自己的 X Developer App 限制決定。詳情請參閱 X API 速率限制文件。

發布到 X（Twitter）

使用 X API（前身為 Twitter API）發布含連結與圖片的基本貼文 JSON 範例：

X Post

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

除非推文中已包含圖片或影片，否則 X 會自動預覽推文中的連結。上述範例會顯示圖片；若移除圖片，就會改為顯示連結預覽。
如果你的影片副檔名不是常見的影片格式（例如 mp4），請使用 isVideo 參數。詳情請參閱 /post 端點。
X 也支援發送不含貼文文字的媒體。如果你不想包含貼文文字，請傳送空字串 post: ""。
單則推文最多可上傳 4 張圖片或影片。發布 Twitter 影片的重要規範與限制請參閱發布 Twitter 影片。
更多資訊請參閱 X 媒體指南與 X 授權。

X 選項

你可以透過 twitterOptions 參數為貼文設定額外的選項。

X Options

{
  "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 選項為可選欄位，用來控制貼文的呈現方式。

array of strings

圖片的替代文字（alt text），可協助無障礙功能與螢幕閱讀器讀取內容。每段 alt text 最多 1,000 個字元。更多資訊請參閱 Alt Text。

array of strings

透過封鎖特定地區，將媒體限制在特定國家可見。可用的國家代碼。不能與 allowCountries 同時使用。更多資訊請參閱地區限制。

array of strings

透過允許特定地區，將媒體限制在特定國家可見。可用的國家代碼。不能與 blockCountries 同時使用。更多資訊請參閱地區限制。

boolean

默认值:false

啟用 Premium 使用者最多 25,000 個字元的長貼文發布功能。更多資訊請參閱長貼文。

boolean

默认值:false

允許已核准帳號發布長於 2 分 20 秒的影片。更多資訊請參閱長影片。

object

以自訂選項與時長進行投票。必填欄位：duration（分鐘數）、options（字串陣列）。更多資訊請參閱投票。

string

透過指定 Tweet ID 引用另一則推文。更多資訊請參閱引用推文。

string

控制誰可以回覆該貼文。可用的值：following、mentioned、subscribers 或 verified。更多資訊請參閱回覆設定。

boolean

默认值:false

將貼文設為僅訂閱者可見。更多資訊請參閱僅訂閱者。

string

使用 SRT 檔案為影片加上字幕。必須是以 .srt 結尾的有效 SRT 檔案 URL。更多資訊請參閱影片字幕。

string

默认值:"en"

字幕的語言。必須是有效的語言代碼。

string

字幕軌道的名稱。最多 150 個字元。

string

為影片設定縮圖（封面圖片）。必須是 JPEG、PNG、BMP 或 WebP 圖片檔案的 URL。更多資訊請參閱影片縮圖，圖片需求請參閱 X 媒體指南。

string

設定影片的標題。會對應到 X Media Studio 中的 title 欄位。更多資訊請參閱影片中繼資料。

string

設定影片的描述。會對應到 X Media Studio 中的 description 欄位。更多資訊請參閱影片中繼資料。

boolean

默认值:false

將長貼文拆成一系列連貫的 thread，並可選擇加入編號與媒體。更多資訊請參閱 Threads。

boolean

默认值:false

自動在每則 thread 末尾以 1/n 格式加上編號。需要 thread: true。

array of strings

為 thread 系列的每則貼文加入媒體物件。每則 thread 會依序加上一個媒體物件。若要跳過某則 thread 的媒體，請使用 null。若要為單一 thread 加入多個媒體，請使用包含多個 URL 的物件。

Alt Text

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

X Alt Text

{
  "twitterOptions": {
    "altText": ["This is my best pic", "😃 here is the next one"] // Array of Alt Texts
  }
}

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

Alt text 無法套用到影片。若 mediaUrls 中含有影片並附上 altText，該影片將不會發布。Alt text 必須為 1,000 個字元以下。

地區限制

透過 blockCountries 與 allowCountries 參數搭配國家代碼，可以將 X 媒體（例如圖片或影片）限制在特定國家可見。貼文本身仍會在所有國家顯示，但媒體在指定國家將無法顯示。

{
  "twitterOptions": {
    "blockCountries": ["US", "CA"]
  }
}

{
  "twitterOptions": {
    "allowCountries": ["GB", "IE"]
  }
}

blockCountries：要封鎖的國家代碼陣列。可用的國家代碼。
allowCountries：允許存取的國家代碼陣列。可用的國家代碼。

blockCountries 與 allowCountries 兩個參數只能使用其中一個。若同時使用這兩個參數，或指定的國家不受 X 支援，地區限制會被忽略。

長貼文

擁有 Premium X 帳號（例如 Premium 或 Premium Plus）的使用者，可以發布最多 25,000 個字元的長貼文。Ayrshare 會自動允許 Premium X 帳號的長貼文發布。如果使用者變更了 X Premium 狀態，請等待 24 小時後才會反映在 Ayrshare 中。你可以透過 /user 或 /analytics 端點檢查使用者的 Premium 訂閱狀態。你也可以透過 longPost body 參數強制系統接受長貼文。做法是在請求中加入以下 JSON：

X Long Post

{
  "twitterOptions": {
    "longPost": true
  }
}

不過，若不具備 Premium 帳號的使用者嘗試發布長推文，系統會回傳 code: 111 錯誤。

長影片

需要 Business 或 Enterprise Plan。 X 要求影片的最長長度為 2 分 20 秒。不過，若你的使用者已被 X 核准可上傳更長的影片（例如使用者的 X 帳號為 Premium 帳號，或加入 Amplify Partner Program），就可以發布長達 10 分鐘以上的影片。

在使用 longVideo 參數前，請確認你的使用者的 X 帳號為 Premium 或已加入 Amplify Partner Program。如果你的使用者的 X 帳號未被授權發布長影片，系統會回傳錯誤。

發布長影片時請使用 longVideo twitterOptions 參數：

X Long Video

{
  "twitterOptions": {
    "longVideo": true
  }
}

提及

在貼文文字中加入 @handle 即可提及其他 X 使用者。例如：

X Mention

{
  "post": "The best social media API @Ayrshare ever!",
  "platforms": ["twitter"]
}

請詳閱關於提及功能的重要規則。

投票

使用 twitterOptions 的 poll 參數進行 X 投票。

X Poll

{
  "twitterOptions": {
    "poll": {
      "duration": 5, // required. Number in minutes
      "options": ["yes", "maybe", "no"] // required
    }
  }
}

duration：投票持續的分鐘數。
options：投票選項的字串陣列。

引用推文

你可以透過指定底層的 Tweet ID 來引用另一則推文。ID 可透過 /post 回應中的 postIds 欄位、取得歷史紀錄取得，或直接從推文 URL 取得：https://twitter.com/Ayrshare/status/1651601430669664256

X Quote Tweet

{
  "twitterOptions": {
    "quoteTweetId": "651601430669664256" // low-level Tweet Id
  }
}

回覆設定

你可以設定貼文的回覆權限，只允許特定類型的使用者回覆。

X Reply Settings

{
  "twitterOptions": {
    "replySettings": "mentioned"
  }
}

replySettings 參數可以是以下其中一個值：

following：只有該 X 帳號正在追蹤的使用者可以回覆。
mentioned：只有在該貼文中被提及的使用者可以回覆。
subscribers：只有該貼文發布者 X 帳號的訂閱者可以回覆。
verified：只有 X 已驗證的使用者可以回覆該貼文。

僅訂閱者

你可以透過 subscribersOnly 參數將貼文設為僅訂閱者可見。

X Subscribers Only

{
  "twitterOptions": {
    "subscribersOnly": true
  }
}

影片字幕

透過提供 SRT 檔案為影片加上 X 字幕（X captions）。使用 twitterOptions 物件中的 subTitleUrl 欄位指定你的 SRT 檔案 URL。

X Subtitles

{
  "twitterOptions": {
    "subTitleUrl": "https://img.ayrshare.com/012/captions.srt",
    "subTitleLanguage": "en",
    "subTitleName": "English"
  }
}

subTitleUrl：有效的 SRT 檔案。URL 必須以 https:// 開頭並以 .srt 結尾，且為有效的 SRT 檔案。
subTitleLanguage：選填：字幕的語言。必須是有效的語言代碼。預設：“en”。
subTitleName：選填：字幕軌道的名稱。此名稱在播放時會顯示給使用者作為選項。最多可支援 150 個字元。預設：“English”。

影片縮圖

為 Twitter/X 影片設定縮圖（封面圖片）。縮圖會在影片播放前顯示，有助於使用者了解影片內容。請在 twitterOptions 物件中使用 thumbNail。

Twitter/X Video Thumbnail

{
  "twitterOptions": {
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg"
  }
}

“thumbNail”：縮圖圖片的 URL。支援的圖片格式為 JPEG、PNG、BMP 與 WebP。
縮圖圖片應能代表影片內容，並具視覺吸引力以帶動互動。
圖片需求請參閱 X 媒體指南。

影片中繼資料

為發布到 X 的影片設定標題與描述。這些欄位會對應到 X Media Studio 中的 title 與 description 欄位。請在 twitterOptions 物件中使用 videoTitle 與 videoDescription 欄位。

X Video Metadata

{
  "twitterOptions": {
    "videoTitle": "My Product Demo",
    "videoDescription": "A short walkthrough of our latest release."
  }
}

videoTitle：影片標題，對應到 X Media Studio 的 title 欄位。
videoDescription：影片描述，對應到 X Media Studio 的 description 欄位。

影片營利（Pro Media）

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

Thread

X Thread（又稱為 tweetstorm）是 X（前身為 Twitter）上一系列相互連接的貼文，讓你能突破單一貼文的字元限制、分享更長的內容，並在檢視時呈現為一個連續的敘事。

發布 Thread

X Thread 可以透過 API 發布。 Thread 是被拆分成多則回覆並在 X 上以一條線串接的貼文。你可以讓系統自動拆分貼文，或在貼文文字中指定 thread 分隔。

X Thread

{
    "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
    }
}

thread: true：依換行符號自動將貼文文字拆分成多則 thread。
threadNumber: true：自動在每則 thread 末尾以 1/n 格式加上編號。例如，第 2 則（共 5 則）thread 末尾會附加 2/5。
mediaUrls: [array of urls]：依序將每個媒體物件（圖片或影片）加到對應的 thread 上。每則 thread 依序只會加上一個媒體物件。

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

Thread 媒體

跳過媒體

在陣列中使用 null 即可跳過某則 thread 的媒體。例如： ["https://site.com/image1.png", null, "https://site.com/image2.png"] 這會將 image1 放在第一則推文、第二則推文無圖片，image2 放在第三則推文。

多個媒體

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

X Thread with Multiple Media URLs

{
  "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。例如：

Example X Thread

{
  "post": "This is tweet 1\n\nThis is tweet 2.",
  "platforms": ["twitter"],
  "twitterOptions": {
    "thread": true
  }
}

會在該 thread 中產生兩則推文。若你想加入段落但不拆成不同的推文，請使用 \u2063\n\u2063\n。

X Thread with Paragraphs

{
  "post": "This is paragraph 1\u2063\n\u2063\nThis is paragraph 2.",
  "platforms": ["twitter"],
  "twitterOptions": {
    "thread": true
  }
}

由於該貼文低於 280 個字元，因此會產生單一推文並包含兩個段落。

刪除 Thread

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

字元限制

更多資訊請參閱 X/Twitter 字元限制。

X 影片相容性

某些影片軟體產生的 MP4 檔案不相容於 X。例如 2019.0.9 版之前的 Camtasia 所產生的 MP4 檔案會被 X 拒絕。此外，多個音訊軌道也常會導致問題。如果你在發布時收到以下訊息，代表該影片與 Twitter 不相容，需要重新編碼。 "file is currently unsupported" 請檢查你使用的影片軟體是否相容。例如，Adobe Media Encoder 有針對 Twitter 1080p Full HD 的匯出預設。

更多 X API 範例請參閱這裡。

僅訂閱者

你可以透過 subscribersOnly 參數將貼文設為僅訂閱者可見。

X Subscribers Only

{
  "twitterOptions": {
    "subscribersOnly": true
  }
}

回覆設定

你可以設定貼文的回覆權限，只允許特定類型的使用者回覆。

X Reply Settings

{
  "twitterOptions": {
    "replySettings": "mentioned"
  }
}

replySettings 參數可以是以下其中一個值：

following：只有該 X 帳號正在追蹤的使用者可以回覆。
mentioned：只有在該貼文中被提及的使用者可以回覆。
subscribers：只有該貼文發布者 X 帳號的訂閱者可以回覆。
verified：只有 X 已驗證的使用者可以回覆該貼文。

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

X BYO API Keys

發布到 X（Twitter）

X 選項

Alt Text

地區限制

長貼文

長影片

提及

投票

引用推文

回覆設定

僅訂閱者

影片字幕

影片縮圖

影片中繼資料

影片營利（Pro Media）

Thread

發布 Thread

Thread 媒體

跳過媒體

多個媒體

Thread 分隔

刪除 Thread

字元限制

X 影片相容性

僅訂閱者

回覆設定

​X BYO API Keys

​發布到 X（Twitter）

​X 選項

​Alt Text

​地區限制

​長貼文

​長影片

​提及

​投票

​引用推文

​回覆設定

​僅訂閱者

​影片字幕

​影片縮圖

​影片中繼資料

​影片營利（Pro Media）

​Thread

​發布 Thread

​Thread 媒體

跳過媒體

多個媒體

​Thread 分隔

​刪除 Thread

​字元限制

​X 影片相容性

​僅訂閱者

​回覆設定

X BYO API Keys

發布到 X（Twitter）

X 選項

Alt Text

地區限制

長貼文

長影片

提及

投票

引用推文

回覆設定

僅訂閱者

影片字幕

影片縮圖

影片中繼資料

影片營利（Pro Media）

Thread

發布 Thread

Thread 媒體

Thread 分隔

刪除 Thread

字元限制

X 影片相容性

僅訂閱者

回覆設定