X BYO API Keys
自 2026 年 3 月 31 日起,所有 X/Twitter 操作都需要使用你自己的 API 憑證。透過 OAuth 連結你的 X 帳號後,請在每個以 X 為目標的請求中包含以下 2 個 header:
尚未連結?請參閱 X BYO Key 設定指南 來連結你的 X 帳號。
| Header | 值 |
|---|---|
X-Twitter-OAuth1-Api-Key | 你的 API Key(Consumer Key) |
X-Twitter-OAuth1-Api-Secret | 你的 API Key Secret(Consumer Secret) |
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
圖片的替代文字(alt text),可協助無障礙功能與螢幕閱讀器讀取內容。每段 alt text 最多 1,000 個字元。更多資訊請參閱 Alt Text。
字幕軌道的名稱。最多 150 個字元。
自動在每則 thread 末尾以 1/n 格式加上編號。需要
thread: true。為 thread 系列的每則貼文加入媒體物件。每則 thread 會依序加上一個媒體物件。若要跳過某則 thread 的媒體,請使用
null。若要為單一 thread 加入多個媒體,請使用包含多個 URL 的物件。Alt Text
為推文的圖片加上替代文字(alt text)。X alt text 是一項無障礙功能,可提供額外的使用者資訊,並協助螢幕閱讀器讀取內容。 請在twitterOptions 物件中使用 altText。
X Alt Text
mediaUrls 陣列中的一張圖片,並依序套用到每張圖片上。
Alt text 無法套用到影片。若
mediaUrls 中含有影片並附上 altText,
該影片將不會發布。Alt text 必須為 1,000 個字元以下。地區限制
透過blockCountries 與 allowCountries 參數搭配國家代碼,可以將 X 媒體(例如圖片或影片)限制在特定國家可見。
貼文本身仍會在所有國家顯示,但媒體在指定國家將無法顯示。
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
code: 111 錯誤。
長影片
需要 Business 或 Enterprise Plan。 X 要求影片的 最長長度 為 2 分 20 秒。 不過,若你的使用者已被 X 核准可上傳更長的影片(例如使用者的 X 帳號為 Premium 帳號,或加入 Amplify Partner Program),就可以發布長達 10 分鐘以上的影片。 發布長影片時請使用longVideo twitterOptions 參數:
X Long Video
提及
在貼文文字中加入@handle 即可提及其他 X 使用者。例如:
X Mention
投票
使用twitterOptions 的 poll 參數進行 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 物件中使用 videoTitle 與 videoDescription 欄位。
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)上一系列相互連接的貼文,讓你能突破單一貼文的字元限制、分享更長的內容,並在檢視時呈現為一個連續的敘事。
發布 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 依序只會加上一個媒體物件。
"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
Thread 分隔
Ayrshare 會自動將貼文文字拆分成適合的推文長度(超過 280 個字元)。 在建立 thread 時,我們會盡可能將完整的句子保留在同一則貼文中。 如果單一句子放不下,就會在句子之間分隔; 若句子非常長,就會在字詞之間分隔; 極少數情況下,如果單一字詞過長,我們才會將該字詞本身拆開。 你也可以在貼文文字中手動加入段落\n\n 來指定要建立一則新的 thread。
如果貼文文字中含有 \n\n,我們就不會再自動將貼文拆分成 thread。
例如:
Example X Thread
\u2063\n\u2063\n。
X Thread with Paragraphs
刪除 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 的匯出預設。

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