Post API 概觀 - Ayrshare API Documentation

Post 端點可讓你將貼文發布到以下社群網路：Bluesky、Facebook、Google Business Profile、Instagram、LinkedIn、Pinterest、Reddit、Snapchat、Telegram、TikTok、X/Twitter 與 YouTube。你可以透過許多選項自訂貼文，例如排程發布、加入自動 hashtag、自動排程等。代理商常在多位權責人員需要在貼文發布前進行核准時使用此功能。可從 /post POST 端點開始發布貼文。

審核流程

如果你的發布流程需要在發送貼文前先進行審核，請將 requiresApproval 欄位設為 true。這相當於暫停該貼文，直到 approved 參數被設為 true 為止。

審核流程範例

在 approved 參數透過 /post PATCH 端點設為 true 之前，該貼文的狀態會維持在 “awaiting approval”。

使用參數發布貼文

使用 /post 端點發布貼文，並將 requiresApproval 欄位設為 true。你也可以同時加入 scheduleDate 等標準參數。

狀態為 awaiting approval

該貼文的狀態會是 “awaiting approval”，並會一直保留到獲得核准為止。

核准貼文

透過 /post PATCH 操作更新該貼文，將 approved 欄位設為 true。該貼文將會在排定的時間發送。

使用備註

選用：在貼文上設定 notes 以供參考，例如指定要由誰核准該貼文。

Publish the Post with Approval

{
  "requiresApproval": true,
  "notes": "need approval by John Smith" // optional
}

如果 scheduleDate 已包含且該日期為過去時間，則貼文在核准後會立即發布。

審核流程影片

請參閱下方影片，了解審核流程的實際範例。

自動 Hashtag

自動為你的貼文加上最相關的 hashtag。 autoHashtag 為一個物件或 Boolean（見下方），可包含以下參數：

max：（選填）要加入的 hashtag 數量，整數範圍 1-10。預設為 2。
position：（選填）字串 “auto” 或 “end”。auto 會將 hashtag 加入貼文內容或貼文末尾。“end” 則僅將 hashtag 加到末尾。

需要付費方案。

{
  "hashtags": {
    "max": 3, // optional: Integer range 1-10
    "position": "auto" // optional: String "auto" or "end"
  }
}

如果你不想使用上述任一選項，可傳入 Boolean 值 true 而非物件。

{
  "autoHashtag": true
}

自動轉貼

以固定間隔自動多次轉貼你的內容，打造能持續維持新鮮度、讓受眾持續看見的常青內容。需要付費方案。參數：

repeat：（必填）要轉貼內容的次數。必須介於 1 到 10 之間。
days：（必填）每次轉貼之間的間隔天數。最少須為 2 天。
startDate：（選填）轉貼排程的開始時間，以 ISO-8601 UTC 格式表示。若未指定，第一則貼文會立即發布。你應使用 startDate 參數，而非最上層的 scheduleDate 參數。

Auto Repost

{
  "repeat": 2, // min 2, max 10
  "days": 5, // min 2
  "startDate": "2021-07-08T12:30:00Z"
}

回應會包含所有未來的排程轉貼，以及每次轉貼的 autoRepostId。

Auto Repost Response

{
  "status": "scheduled",
  "scheduleDate": "2025-06-13T12:30:00.000Z",
  "id": "eIT96IYEodNuzU4oMmwG",
  "refId": "9abf1426d6ce9122ef11c72bd",
  "autoRepostId": "F5wdoaOAAGtDQVciExSxL",
  "post": "The most important things are the hardest to say - Stephen King"
}

建立自動轉貼時，系統會指派一個 autoRepostId 來追蹤這一系列貼文。你可以透過 History 呼叫搭配 autoRepostId 取得該貼文的所有自動轉貼。如果需要刪除某次轉貼，可以使用 DELETE 呼叫搭配貼文 ID 進行刪除。

重要：使用自動轉貼時，請務必遵守各社群網路的發文頻率規範，避免帳號受到限制。注意：autoRepost 功能不能與 scheduleDate 同時使用。若同時包含這兩個參數，scheduleDate 會優先套用，並忽略 autoRepost。請改用 startDate 參數。

首則留言

在貼文發布後自動加上一則首則留言（可包含媒體）。對於 TikTok，該留言會延後到影片處理完成後才發布（請參閱首則留言處理時間）。在自己的社群貼文上發布首則留言，有助於帶動互動並為後續的討論定調。

{
  "firstComment": {
    "comment": "My first comment", // required
    "mediaUrls": ["https://..."] // Facebook, LinkedIn, and X/Twitter only
  }
}

首則留言處理時間

對大多數社群網路而言，API 回應會有所延遲，因為我們的系統必須（1）等待原始貼文完全發布，然後（2）將留言加到該已發布貼文上。這個順序流程會造成約 20 秒的延遲。 TikTok 的處理方式不同。 TikTok 以非同步方式處理影片，因此在 TikTok 的 post.publish.publicly_available webhook 解析出真正的影片 id 之前，貼文的 id 會是 "pending"（請參閱 TikTok 處理）。因此 /post 回應會立即以 status: "pending" 回傳 TikTok 的首則留言，等 TikTok 完成處理並觸發 tikTokPublished Scheduled Action webhook 後，留言就會自動發布。TikTok 不保證處理時間，因此並沒有固定的延遲。 TikTok 重要注意事項：若要在 TikTok 上正確使用首則留言，貼文的 visibility 參數必須設為 public。非公開影片永遠不會收到 publicly_available webhook，因此無法發布其首則留言；在這種情況下，Ayrshare 會直接回傳留言錯誤，而不會讓它一直維持 pending。

冪等貼文

冪等性（Idempotency）是一項選用功能，可確保請求即使不小心被送出多次，也只會被執行一次。使用 API 發布內容時，你可以在請求 body 中包含選用的 idempotencyKey 參數來唯一識別該操作。這讓你可以安全地重試發布請求，而不會有建立重複貼文的風險。若要使用冪等性，請在 /post POST 請求的 JSON body 中加入 idempotencyKey 參數：

Idempotency Key

{
  "idempotencyKey": "Unique Key"
}

idempotencyKey 的值應為 User Profile 中唯一的字串。若對某個 User Profile 送出相同 idempotencyKey 的請求，不論該貼文的狀態為何（success、error、pending 或 deleted），都會回傳錯誤，表示發現重複的鍵值。

API 必須先接收並處理 POST 請求，才能儲存 idempotency key 並檢查是否重複。然而，如果多個具有相同 idempotencyKey 的 POST 請求被同時送出，或被排程於相同的發布時間， API 可能無法偵測到重複的鍵值。這是因為 API 會以平行的方式處理這些並發或同時排程的請求，在還沒來得及註冊任何單一請求的 idempotency key 之前就會全部開始執行。因此，在同時提交或同時執行排程貼文的情況下，並不保證能捕捉到重複的 idempotency key。

使用冪等性有助於在重試失敗請求或處理網路問題時，避免不小心建立重複的貼文。不過仍建議在你的應用程式中實作適當的錯誤處理與重試機制，以更順暢地處理潛在的失敗情境。

圖片與影片需求

發布圖片與影片時，每個平台都有不同的需求，但不用擔心。我們的系統會在發送前先驗證你的貼文，若有問題會回傳錯誤訊息。詳細的圖片與影片規範請參閱下方連結。

圖片與影片指南

有效的 URL

請確認你的媒體 URL 有效，並能直接存取媒體。第一個測試方式是把 URL 貼到瀏覽器中打開。如果圖片在瀏覽器中無法載入或無法下載，通常也會發布失敗。例如，會開啟 DropBox Web App 的 DropBox URL 是無法使用的。

如果你有 Google Drive 分享網址或 Dropbox 分享網址，發布貼文或留言時可以直接在 mediaUrls 參數中使用該網址。Ayrshare 會自動將分享網址轉換為下載連結。

我們會透過 HEAD 請求驗證媒體 URL。請確認託管服務未封鎖 HEAD 請求，否則貼文會以 403 錯誤失敗。例如，以下是對媒體 URL 發送的 HEAD 請求：

Fetch HEAD Request

const run = async () => {
  const url = "https://img.ayrshare.com/012/gb.jpg";
  return await fetch(url, {
    method: "HEAD"
  })
    .then((res) => {
      if (res.ok) {
        return console.log("Success:", res.status, res.statusText);
      } else {
        return console.error("Error:", res.status, res.statusText, res);
      }
    })
    .catch((error) => {
      return console.error("Error Catch:", error);
    });
};

run();

自動媒體保護

Ayrshare 內建媒體保護機制，可在發布過程中偵測並解決特定的媒體傳輸問題。當貼文成功發布，但過程中偵測並解決了某項內容問題時，postIds[] 中每個受影響的項目都會包含選用的 contentIssues 物件，讓你可以識別並修正根本問題：

{
    "postIds": [
        {
            "status": "success",
            "platform": "instagram",
            "id": "17878176260289172",
            "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
            "contentIssues": {
                "originMediaHostFailed": true,
                "details": ["Media URL could not be retrieved by the social network. Successfully posted using Ayrshare automated media protection."]
            }
        }
    ]
}

如果你在回應中看到 originMediaHostFailed，請檢查你的媒體託管設定。常見原因與解決方法請參閱 Meta Media Crawler Blocked。

空白與特殊字元

建議你的媒體 URL 避免使用以下字元：

URL 中的空白。
URL 中經過 URL 編碼的空白。
URL 中的特殊字元（即使經過 URL 編碼），例如帶重音符號的 é。

例如：

https://img.ayrshare.com/012/test .webp

這個 URL 會失敗，因為 test .webp 中包含空白。我們也不建議在 URL 中使用經過 URL 編碼的空白（例如 %20），這在某些社群網路上也可能造成問題。再看這個 Unsplash 圖片：

https://unsplash.com/photos/a-house-in-the-middle-of-a-field-with-trees-in-the-background-znbmh2-cIj0

這個 Unsplash 圖片會失敗，因為它並非直接存取圖片，而是顯示 Web App。

清理檔案名稱與 URL

你可以用類似 /[^a-z0-9\/\.]/gi 的正規表達式來清理檔案名稱。

const sanitizeFileName = (url) => url.replace(/[^a-z0-9\/\.]/gi, "_");
sanitizeFileName("tést .webp"); // t_st_.webp

或清理整個 URL：

const sanitizeUrl = (url) => {
  const [protocol, rest] = url.split("://");
  const [domain, ...path] = rest.split("/");
  const sanitizedPath = path.join("/").replace(/[^a-z0-9\/\.]/gi, "_");
  return `${protocol}://${domain}/${sanitizedPath}`;
};

// Output: https://img.ayrshare.com/012/t_st_.webp
sanitizeUrl("https://img.ayrshare.com/012/tést .webp");

補充資訊

如果你使用自架託管，請確認該 URL 可從外部存取，且不需要特殊權限。
關於處理不明副檔名的影片（通常是像 AWS S3 這類簽章 URL），請參閱下方說明。
如果你使用簽章 URL（例如 S3），我們建議將 URL 的有效期限設為至少 7 天。這讓我們的團隊可以協助處理你在發布貼文時遇到的任何問題。
可透過我們的媒體驗證工具測試媒體 URL 是否存在。

下載速度

請確認你的媒體託管具有較快的網路連線速度，尤其是下載速度。你可以在 pingdom 測試你的媒體託管效能，建議至少達到 B 級。

影片副檔名

如果你的 URL 沒有以已知的影片副檔名（例如 mp4）結尾，可以在貼文中使用 isVideo: true 欄位來指定該 mediaUrl 為影片。Ayrshare 會嘗試判斷檔案類型，例如 MOV。不過我們仍建議影片檔案明確使用已知的副檔名（例如 mp4）結尾，這樣在各社群網路上的成功率會較高。

僅圖片或影片

有部分社群網路支援不含貼文文字的媒體貼文。如果你不想包含貼文文字，請傳送空字串：post: ""。以下社群網路支援空白/無貼文文字：Facebook、Instagram、LinkedIn、Threads、TikTok 與 X/Twitter。

測試圖片與影片

不妨使用產生隨機文字與隨機圖片或影片來加速你的測試。不要再絞盡腦汁為每個測試貼文想不同的內容了！

換行

如果你想在貼文中換行（新增一行），請使用不可見的換行符號 \u2063\n。例如 This is a new\u2063\nline.我們也建議在 Postman 中先測試，看看該換行符號在你使用的語言中如何被解析。例如 PHP 通常只需使用 \n。部分社群網路目前並不支援貼文文字中的換行。

多平台貼文與媒體

此功能可讓你在單一 API 呼叫中，為不同的社群網路自訂貼文內容與媒體。你可以透過為 post 與 mediaUrls 欄位使用物件的方式，為每個平台指定專屬的文字與/或圖片。

為 post 和/或 mediaUrls 欄位使用物件結構。
以平台名稱作為 key 指定各平台專屬的內容。
加入 default key，作為未明確指定平台的預設內容。

{
  "post": {
    "instagram": "Great IG pic!",
    "facebook": "Great FB pic!",
    "default": "Great default pic!"
  },
  "platforms": ["instagram", "facebook", "linkedin"],
  "mediaUrls": {
    "instagram": "https://img.ayrshare.com/012/gb.jpg",
    "linkedin": "https://img.ayrshare.com/012/gb.jpg",
    "default": "https://img.ayrshare.com/012/gb.jpg"
  }
}

在上述範例中：

Instagram 會使用其專屬的文字與圖片 URL。
Facebook 會使用其專屬的文字與預設圖片 URL。
LinkedIn 會使用預設文字與其專屬的圖片 URL。

如果你需要在不同平台上發布多張圖片，建議為每個平台建立各自的貼文，而不要使用這種多平台結構。

Profile Keys

透過在 body 參數中提供使用者的 Profile Key，即可代表該使用者發布貼文，回應中也會包含額外的資料。需要 Business 或 Enterprise Plan。

Profiles

Rich Text 貼文

你可以加入 rich text，例如 ”𝓗𝓮𝓵𝓵𝓸, how about a little 𝗯𝗼𝗹𝗱 𝘁𝗲𝘅𝘁 and 𝘪𝘵𝘢𝘭𝘪𝘤𝘴 𝘵𝘦𝘹𝘵 and an x₂?”。可在 Twitter、Facebook、LinkedIn、Telegram、Instagram 等平台使用 rich text。若要發布到 Reddit，請使用 Reddit-flavored Markdown 格式。系統透過 HTML 元素指定 rich text 類型，並將其轉換為 unicode。例如：

{
    "post": "<var>Hello</var>, how about a little <b>bold text</b> and <i>italics text</i> and an x<sub>2</sub>?"
    "platforms": ["twitter"]
}

HTML 元素

HTML	範例
<b>Nice One!</b>	Nice One!
<strong>Hello, world!</strong>	Hello, world!
<em>World</em>	World
normal <i>italics <b>bold italics</b></i>	normal italics bold italics
`<b>Hello</b>, world!`	`Hello, world!`
`<b>Hello</b>, world!`	`Hello``, world!`
<samp>123</samp>	𝟷𝟸𝟹
<var>Hello</var>	𝓗𝓮𝓵𝓵𝓸
x<sub>2</sub>	x₂
x<sup>2</sup>	x²

CSS 代碼

代碼	範例	結果
\u00B0	It’s 25\u00B0C today!	It’s 25°C today!
\u2063\n	This is a new\u2063\nline.	This is a new line.

排程貼文

建立排程貼文

你可以透過指定 scheduleDate 參數（以 Zulu/UTC 表示的日期時間）來排程未來的貼文。Zulu Time 又稱為 Coordinated Universal Time（UTC），是全球通用的時間標準。例如使用 YYYY-MM-DDThh:mm:ssZ 格式，並以 2026-07-08T12:30:00Z 的形式傳送。更多範例請參閱 utctime。

{
  "post": "Hello, world!",
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["facebook", "instagram"],
  "scheduleDate": "2023-07-08T12:30:00Z"
}

若要將本地時間轉換為 Zulu/UTC 時間，請參閱 https://www.utctime.net/。若排定的日期時間為過去時間，該貼文會立即發送。

如果排程貼文中包含 mediaUrl，該媒體必須在排定的發布時間仍然可存取。例如，如果貼文排定於 2026 年 3 月 5 日發布，該媒體必須在 2026 年 3 月 5 日當天仍然可存取。

排程貼文與立即貼文的錯誤處理差異立即貼文與排程貼文在驗證錯誤的處理方式上有一個重要的差異：

立即貼文
- 當你選擇立即發布（未指定 scheduleDate）時，若其中一個平台的驗證失敗，其他平台仍會繼續處理。例如，若貼文超過 Twitter 的字元上限，但符合 Facebook 與 Instagram 的規範，該貼文在 Twitter 上會失敗，但仍會成功發布到 Facebook 與 Instagram。
排程貼文
- 當你排程貼文到未來時間發布（指定 scheduleDate）時，所有平台都必須通過初步驗證檢查，貼文才會被成功排程。若有任何一個平台未通過這些預先驗證，整個排程操作都會被拒絕並立即回傳錯誤。
- 不過，某些平台專屬的錯誤要到實際發布時間才會被偵測到。在這種情況下，排程貼文仍會嘗試發布到所有平台，個別平台的失敗會在最終結果中回報，且不會影響其他平台。

查詢排程貼文狀態

你可以透過以下幾種方式查詢排程貼文的狀態：

設定 Webhook Scheduled Action，自動接收排程貼文的狀態通知。此功能適用於 Business Plan，是我們推薦的方法。
透過 GET 呼叫搭配貼文 ID 取得排程貼文的狀態。
在 Ayrshare Dashboard 中查詢狀態。先切換到該貼文所屬的 User Profile，再前往「Posts」頁面，透過 Ayrshare Post ID 進行搜尋。

暫停排程貼文

你可以暫停尚未發布的排程貼文。暫停後，該貼文在被取消暫停之前都不會發布。使用 PATCH 呼叫來暫停或取消暫停排程貼文。請注意，若貼文被取消暫停時 scheduleDate 已是過去時間，該貼文會立即發布。建議在取消暫停前先更新 scheduleDate。

縮短網址

貼文中的連結可以透過 Ayrshare 的連結縮短工具縮短。在發送貼文時，可透過 shortenLinks 參數開啟自動縮短網址。需要 Max Pack。

{
  "post": "Hello, world with a link https://www.ayrshare.com",
  "platforms": ["linkedin"],
  "shortenLinks": true
}

Unsplash 圖片

unsplash body 參數可使用以下幾種形式：

隨機圖片：random 會回傳一張隨機的 Unsplash 圖片。
以搜尋詞取得圖片：值為字串搜尋關鍵字；例如 money 會依 money 主題選取一張隨機圖片。
圖片 ID：值為 ID 的陣列；例如 [“HubtZZb2fCM”] 對應圖片 https://unsplash.com/photos/HubtZZb2fCM

{
  "post": "Hello, world!",
  "platforms": ["instagram"],
  "unsplash": "random",
  "unsplash": "search term", // unsplash: "money"
  "unsplash": ["unsplash image ID"] // unsplash: ["HubtZZb2fCM"]
}

若要從 Unsplash 複製 URL 放到 mediaUrls 中，請務必複製圖片位址，而不是頁面 URL。相關細節請參閱這個範例。

​審核流程

​審核流程範例

​審核流程影片

​自動 Hashtag

​自動轉貼

​首則留言

​首則留言處理時間

​冪等貼文

​圖片與影片需求

圖片與影片指南

​有效的 URL

​自動媒體保護

​空白與特殊字元

​清理檔案名稱與 URL

​補充資訊

​下載速度

​影片副檔名

​僅圖片或影片

​測試圖片與影片

​換行

​多平台貼文與媒體

​Profile Keys

Profiles

​Rich Text 貼文

​HTML 元素

​CSS 代碼

​排程貼文

​建立排程貼文

​查詢排程貼文狀態

​暫停排程貼文

​縮短網址

​Unsplash 圖片

審核流程

審核流程範例

審核流程影片

自動 Hashtag

自動轉貼

首則留言

首則留言處理時間

冪等貼文

圖片與影片需求

有效的 URL

自動媒體保護

空白與特殊字元

清理檔案名稱與 URL

補充資訊

下載速度

影片副檔名

僅圖片或影片

測試圖片與影片

換行

多平台貼文與媒體

Profile Keys

Rich Text 貼文

HTML 元素

CSS 代碼

排程貼文

建立排程貼文

查詢排程貼文狀態

暫停排程貼文

縮短網址

Unsplash 圖片