跳转到主要内容

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

X 選項

你可以透過 twitterOptions 參數為貼文設定額外的選項。
X Options
X 選項為可選欄位,用來控制貼文的呈現方式。
altText
array of strings
圖片的替代文字(alt text),可協助無障礙功能與螢幕閱讀器讀取內容。每段 alt text 最多 1,000 個字元。更多資訊請參閱 Alt Text
blockCountries
array of strings
透過封鎖特定地區,將媒體限制在特定國家可見。可用的國家代碼不能與 allowCountries 同時使用。更多資訊請參閱 地區限制
allowCountries
array of strings
透過允許特定地區,將媒體限制在特定國家可見。可用的國家代碼不能與 blockCountries 同時使用。更多資訊請參閱 地區限制
longPost
boolean
默认值:false
啟用 Premium 使用者最多 25,000 個字元的長貼文發布功能。更多資訊請參閱 長貼文
longVideo
boolean
默认值:false
允許已核准帳號發布長於 2 分 20 秒的影片。更多資訊請參閱 長影片
poll
object
以自訂選項與時長進行投票。必填欄位:duration(分鐘數)、options(字串陣列)。更多資訊請參閱 投票
quoteTweetId
string
透過指定 Tweet ID 引用另一則推文。更多資訊請參閱 引用推文
replySettings
string
控制誰可以回覆該貼文。可用的值:followingmentionedsubscribersverified更多資訊請參閱 回覆設定
subscribersOnly
boolean
默认值:false
將貼文設為僅訂閱者可見。更多資訊請參閱 僅訂閱者
subTitleUrl
string
使用 SRT 檔案為影片加上字幕。必須是以 .srt 結尾的有效 SRT 檔案 URL。更多資訊請參閱 影片字幕
subTitleLanguage
string
默认值:"en"
字幕的語言。必須是有效的語言代碼
subTitleName
string
字幕軌道的名稱。最多 150 個字元。
thumbNail
string
為影片設定縮圖(封面圖片)。必須是 JPEG、PNG、BMP 或 WebP 圖片檔案的 URL。更多資訊請參閱 影片縮圖,圖片需求請參閱 X 媒體指南
videoTitle
string
設定影片的標題。會對應到 X Media Studio 中的 title 欄位。更多資訊請參閱 影片中繼資料
videoDescription
string
設定影片的描述。會對應到 X Media Studio 中的 description 欄位。更多資訊請參閱 影片中繼資料
thread
boolean
默认值:false
將長貼文拆成一系列連貫的 thread,並可選擇加入編號與媒體。更多資訊請參閱 Threads
threadNumber
boolean
默认值:false
自動在每則 thread 末尾以 1/n 格式加上編號。需要 thread: true
mediaUrls
array of strings
為 thread 系列的每則貼文加入媒體物件。每則 thread 會依序加上一個媒體物件。若要跳過某則 thread 的媒體,請使用 null。若要為單一 thread 加入多個媒體,請使用包含多個 URL 的物件。

Alt Text

為推文的圖片加上替代文字(alt text)。X alt text 是一項無障礙功能,可提供額外的使用者資訊,並協助螢幕閱讀器讀取內容。 請在 twitterOptions 物件中使用 altText
X Alt Text
每個 alt text 必須對應到 mediaUrls 陣列中的一張圖片,並依序套用到每張圖片上。
Alt text 無法套用到影片。若 mediaUrls 中含有影片並附上 altText, 該影片將不會發布。Alt text 必須為 1,000 個字元以下。

地區限制

透過 blockCountriesallowCountries 參數搭配國家代碼,可以將 X 媒體(例如圖片或影片)限制在特定國家可見。 貼文本身仍會在所有國家顯示,但媒體在指定國家將無法顯示。
  • blockCountries:要封鎖的國家代碼陣列。可用的國家代碼
  • allowCountries:允許存取的國家代碼陣列。可用的國家代碼
blockCountriesallowCountries 兩個參數只能使用其中一個。 若同時使用這兩個參數,或指定的國家不受 X 支援,地區限制會被忽略。

長貼文

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

提及

在貼文文字中加入 @handle 即可提及其他 X 使用者。例如:
X Mention
請詳閱關於提及功能的重要規則

投票

使用 twitterOptionspoll 參數進行 X 投票。
X Poll
  • duration:投票持續的分鐘數。
  • options:投票選項的字串陣列。

引用推文

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

回覆設定

你可以設定貼文的回覆權限,只允許特定類型的使用者回覆。
X Reply Settings
replySettings 參數可以是以下其中一個值:
  • following:只有該 X 帳號正在追蹤的使用者可以回覆。
  • mentioned:只有在該貼文中被提及的使用者可以回覆。
  • subscribers:只有該貼文發布者 X 帳號的訂閱者可以回覆。
  • verified:只有 X 已驗證的使用者可以回覆該貼文。

僅訂閱者

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

影片字幕

透過提供 SRT 檔案 為影片加上 X 字幕(X captions)。使用 twitterOptions 物件中的 subTitleUrl 欄位指定你的 SRT 檔案 URL。
X Subtitles
  • subTitleUrl:有效的 SRT 檔案。URL 必須以 https:// 開頭並以 .srt 結尾, 且為有效的 SRT 檔案。
  • subTitleLanguage:選填:字幕的語言。必須是有效的 語言 代碼。預設:“en”。
  • subTitleName:選填:字幕軌道的名稱。此名稱在播放時會顯示給 使用者作為選項。最多可支援 150 個字元。 預設:“English”。

影片縮圖

為 Twitter/X 影片設定縮圖(封面圖片)。縮圖會在影片播放前顯示,有助於使用者了解影片內容。請在 twitterOptions 物件中使用 thumbNail
Twitter/X Video Thumbnail
  • “thumbNail”:縮圖圖片的 URL。支援的圖片格式為 JPEG、PNG、BMP 與 WebP。
  • 縮圖圖片應能代表影片內容,並具視覺吸引力以帶動互動。
  • 圖片需求請參閱 X 媒體指南

影片中繼資料

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

影片營利(Pro Media)

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

Thread

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

發布 Thread

X Thread 可以透過 API 發布。 Thread 是被拆分成多則回覆並在 X 上以一條線串接的貼文。 你可以讓系統自動拆分貼文,或在貼文文字中指定 thread 分隔
X Thread
  • 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
在此範例中,第一則推文會包含 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
會在該 thread 中產生兩則推文。 若你想加入段落但不拆成不同的推文,請使用 \u2063\n\u2063\n
X Thread with Paragraphs
由於該貼文低於 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 的匯出預設。 Adobe Media Encoder 更多 X API 範例請參閱這裡。

僅訂閱者

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

回覆設定

你可以設定貼文的回覆權限,只允許特定類型的使用者回覆。
X Reply Settings
replySettings 參數可以是以下其中一個值:
  • following:只有該 X 帳號正在追蹤的使用者可以回覆。
  • mentioned:只有在該貼文中被提及的使用者可以回覆。
  • subscribers:只有該貼文發布者 X 帳號的訂閱者可以回覆。
  • verified:只有 X 已驗證的使用者可以回覆該貼文。