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

# Instagram API

> 使用 Instagram API 發布內容的選項

<Info>
  如果你在連結 Instagram 時遇到問題，請參閱[疑難排解
  指南](/help-center/technical-support/facebook_or_instagram_linking_issues)。
</Info>

<Info>
  如果你的媒體託管於你自己的伺服器或 CDN，請確認 Meta 的發布爬蟲
  可以擷取到該媒體。如果你看到 Ayrshare 錯誤代碼 440（「social network could not download media from this URL」）或錯誤代碼 138，且細節中出現「Restricted by robots.txt」，請參閱 [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked)。
</Info>

<div class="video-container">
  <iframe width="380" height="200" src="https://www.youtube.com/embed/3F7mbVN0qrw" title="Posting to Instagram API" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" />
</div>

Instagram API 有以下需求與限制。

<ul class="custom-bullets">
  <li>
    需要與 Facebook 粉絲專頁連結的 Business 或 Creator Instagram 帳號 —
    [請參閱這裡](/dashboard/connect-social-accounts/instagram)。
  </li>

  <li>Instagram 在 24 小時內只允許 50 則貼文。有關 `usedQuota` 的說明請參閱下方。</li>

  <li>
    `post` 文字最多可包含 *5 個 hashtag*（例如 #wildtimes）以及 *3 個 username 提及*
    （例如 @natgeo）。
  </li>

  <li>被 @提及的 Instagram 使用者會收到通知。</li>
  <li>貼文最多 2,200 個字元。</li>

  <li>
    支援多圖/多影片貼文，會以輪播形式發布。單一貼文最多可包含 10 個
    影片與圖片。
  </li>

  <li>
    Instagram 不支援透過 API 刪除貼文。刪除必須在 Instagram App 內
    手動操作。
  </li>

  <li>
    如果你的 Reel 影片副檔名不是常見的影片格式（例如 mp4），請使用 `isVideo`
    參數。詳情請參閱 [/post 端點](/apis/post/post)。
  </li>

  <li>
    Instagram 也支援發送不含貼文文字的媒體。如果你不想包含貼文文字，
    請傳送空字串 `post: ""`。
  </li>

  <li>更多資訊請參閱 [Instagram 媒體指南](/media-guidelines/instagram) 與 [Instagram 授權](/dashboard/connect-social-accounts/instagram)。</li>
</ul>

## 發布到 Instagram

發布含圖片與 hashtag 的基本 Instagram 貼文的 JSON 範例：

```json Instagram Post theme={"system"}
{
  "post": "The best IG ever #best #awesome https://www.instagram.com",
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["instagram"]
}
```

Instagram 貼文中的 hashtag 可點擊，但連結則否。

<Note>
  圖片與影片的長寬比、以及影片的長度對於能否成功發布到 Instagram 非常重要。若不符合需求，貼文會被拒絕。

  [請參閱圖片與影片指南的 Instagram 章節](/media-guidelines/instagram)。
</Note>

## Instagram Business 或 Creator 帳號

你的 Instagram 帳號必須是 Business 或 Creator 帳號，並已連結至 Facebook 粉絲專頁。此設定免費且容易完成。

詳細操作說明請參閱：

<Card title="Instagram 連結" icon="link" href="/dashboard/connect-social-accounts/instagram" horizontal />

## 圖片與影片的輪播

你可以將多張圖片或 Reel 影片以輪播形式發布到 Instagram；單一輪播中最多可包含 10 個圖片或影片。
只要在 `mediaUrls` 陣列中加入更多圖片或影片，系統就會自動建立輪播。

```json Instagram Carousel Post theme={"system"}
{
  // Max 10 images or videos
  "mediaUrls": ["https://url.com/image.jpg", "https://url.com/video.mp4"]
}
```

<Note>
  影片 URL 必須以已知的副檔名（例如 `mp4`）結尾。Instagram 輪播不支援
  `isVideo` 參數。
</Note>

## Instagram Reels

在 Instagram 上，影片貼文稱為 Reel。
你可以透過以下可選的 `instagramOptions` 選項，將影片發布到 Instagram Reels API。

```json Instagram Reels Options theme={"system"}
{
  "instagramOptions": {
    "shareReelsFeed": true,
    "audioName": "The Weeknd - Blinding Lights",
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg", // if used, thumbNailOffset will be ignored.
    "thumbNailOffset": 30000
  }
}
```

<ul class="custom-bullets">
  <li>
    詳細的影片需求請參閱 [Reels API 影片需求](/media-guidelines/instagram#reels)。
  </li>

  <li>
    `shareReelsFeed`：Boolean。設為 `true` 表示 Reel *可以* 同時出現在
    **動態消息** 與 **Reels** 分頁；設為 `false` 表示 Reel *僅可* 出現在 **Reels**
    分頁。此值只是提示 Instagram 你希望 Reel 出現的位置，並不代表
    Reel *實際上* 一定會出現在 **Reels** 或 **動態消息** 分頁，
    因為 Reel 可能不符合資格，或未被 Instagram 演算法選中。
  </li>

  <li>
    `audioName`：字串，Reels 媒體的音樂音訊名稱。你只能重新命名一次，
    在建立 reel 時或事後從音訊頁面重新命名。例如 `"The Weeknd - Blinding
            Lights"`。
  </li>

  <li>
    `thumbNail`：字串，Reel 封面圖片（縮圖）的 URL。詳情請參閱
    [thumbNail 說明](/apis/post/social-networks/instagram#reels-thumbnails)。
  </li>

  <li>
    `thumbNailOffset`：整數，縮圖影格的毫秒位移。詳情請參閱
    [thumbNailOffset 說明](/apis/post/social-networks/instagram#reels-thumbnails)。
  </li>
</ul>

請參閱 [Reels API 影片需求](/media-guidelines/instagram#reels)，或 [使用 Instagram Reels API 的範例](https://www.ayrshare.com/blog/instagram-reels-api-how-to-post-videos-to-reels-using-a-social-media-api/)。

你也可以設定 [Reels 封面 URL](/apis/post/social-networks/instagram#reels-thumbnails) 與 [地點與使用者標籤](/apis/post/social-networks/instagram#user-tags-and-locations)。

## Trial Reels

Trial reel 是一種 Reel，發布之初僅會向非追蹤者顯示，讓你可以先用新受眾測試 Reel 的表現，之後才會觸及到現有的追蹤者。在 `instagramOptions` 中設定 `trialParams.graduationStrategy` 即可將 Reel 以 trial 形式發布。

```json Instagram Trial Reel theme={"system"}
{
  "post": "Testing this with a fresh audience first",
  "mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
  "platforms": ["instagram"],
  "instagramOptions": {
    "trialParams": {
      "graduationStrategy": "MANUAL"
    }
  }
}
```

`graduationStrategy` 控制 trial reel 之後如何「graduate」— 也就是同時顯示給你的追蹤者。當提供 `trialParams` 時此欄位必填，且必須為以下其中之一：

<ul class="custom-bullets">
  <li>
    <code>"MANUAL"</code> — 貼文會維持為 trial reel，直到你在 Instagram App 中
    手動將其 graduate 為止。
  </li>

  <li>
    <code>"SS\_PERFORMANCE"</code> — Meta 會依 Reel 對非追蹤者的早期表現
    自動 graduate。
  </li>
</ul>

<Note>
  Graduation 本身（將已發布的 trial reel 推廣給追蹤者）目前尚未由
  Meta API 公開，必須在 Instagram App 中手動操作。一旦 Meta 公開此功能，Ayrshare 會新增
  對應的 graduation 端點。
</Note>

### Trial reel 限制

當以下任一條件未滿足時，Trial reel 請求會在 Ayrshare 邊界處被拒絕 — 尚未呼叫 Meta：

<ul class="custom-bullets">
  <li>必須只有一個媒體 URL，並以 <code>.mp4</code> 或 <code>.mov</code>（不分大小寫）結尾。不支援輪播。</li>
  <li><code>instagramOptions.stories</code> 不得為 <code>true</code>。Stories 不能是 trial reel。</li>
  <li><code>graduationStrategy</code> 必須存在，且必須為 <code>"MANUAL"</code> 或 <code>"SS\_PERFORMANCE"</code>（區分大小寫）。</li>
</ul>

失敗會回傳三種 Ayrshare 錯誤代碼之一 — 完整內容請參閱 [Instagram Trial Reel 錯誤](/errors/errors-ayrshare#instagram-specific-error-codes)（<code>447</code>、<code>448</code>、<code>449</code>）。

## Instagram Stories

你可以使用以下 `instagramOptions` 將單張圖片或單部影片以 Instagram Story 發布。Instagram Stories 會在 24 小時後消失。

```json Stories Post theme={"system"}
{
  "post": "The description of the video",
  "mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
  "instagramOptions": {
    "stories": true
  }
}
```

請參閱 [Stories API 需求](/media-guidelines/instagram#stories)。

<ul class="custom-bullets">
  <li>
    Instagram Stories 不支援貼文文字 — `post` 欄位中提供的任何文字（包含
    提及）都會被忽略。
  </li>

  <li>Stories 會在 24 小時後過期。</li>

  <li>
    Instagram 目前只支援 Instagram Business Account 發布 Story，
    Creator Account 不支援。
  </li>

  <li>Instagram Stories 不支援 collaborators。</li>
  <li>Instagram 不支援發布貼紙（例如連結、投票、地點）。</li>
</ul>

## Reels 縮圖

你可以選擇 Reel 中的某一格作為縮圖影像，或使用外部 URL 提供自己的封面圖片（縮圖）。

```json Instagram Thumbnail theme={"system"}
{
  "instagramOptions": {
    // milliseconds
    "thumbNailOffset": 30000,
    // If both thumbNail and thumbNailOffset includes, thumbNail will be used.
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg"
  }
}
```

Offset 是影片 Reel 中縮圖影格的位置（毫秒）。預設值為 `0`，即 Reel 的第一格。

如果你同時指定縮圖 URL 與縮圖 offset，縮圖 offset 會被忽略。

Reel 縮圖必須符合 [Reels 縮圖需求](/media-guidelines/instagram#reels-thumbnails)。
帶重新導向的簽章 URL 不保證能相容於封面 URL。
建議使用非簽章 URL，或使用 [/media 端點](/apis/media/overview)。

## 替代文字

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

<ul class="custom-bullets">
  <li>每張圖片的 alt text 最多支援 1,000 個字元。</li>
  <li>Instagram 不支援 Reels 或 Stories 的 alt text。</li>
</ul>

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

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

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

## 使用者標籤與地點

<Info>
  當你在貼文中使用其他 Instagram 使用者的 username 時，該使用者會收到通知。請小心避免
  對使用者進行垃圾騷擾或重複使用其 username 發布內容。否則 Instagram 可能會停權
  或停用你的帳號。
</Info>

透過 `instagramOptions` 參數，可以在圖片或 Reel 上標註 Instagram 使用者，也可以在圖片、影片或 Reel 上標註地點。

### 地點

地點透過 `locationId` 指定，其為 Facebook Page ID 或 Facebook Page 名稱。例如，[Guggenheim Museum](https://www.facebook.com/guggenheimmuseum) 的 Facebook page ID 是 `7640348500`，或 Facebook page 名稱 `"@guggenheimmuseum"`。粉絲專頁必須關聯有實體地點。

```json Instagram Location theme={"system"}
// Using the Facebook Page Id - must be associated with a location
{
    "instagramOptions": {
        "locationId": 7640348500 // Guggenheim Museum Page Id
    }
}

// Using the Facebook Page name - must be associated with a location
{
    "instagramOptions": {
        "locationId": "@guggenheimmuseum" // Guggenheim Museum Page name. Must begin with @
    }
}
```

你可以使用 [brand 端點](/apis/brand/overview) 查詢 `locationId`（Page ID）。請注意，該粉絲專頁必須有列出地點，否則 locationId 會回傳錯誤。

<Note>輪播中的圖片或影片不支援此功能。</Note>

### 使用者標籤

Instagram 標籤讓你可以在貼文中標註其他 Instagram 使用者。
使用者透過 `userTags` 指定，其為一個物件陣列，包含 Instagram username 與 x/y 座標（僅圖片）。使用者標籤可以加在單張圖片或 Reel 上，但不能加在一般影片、多張圖片或 Stories 上。

<ul class="custom-bullets">
  <li>Username 必須是公開的 Instagram 帳號。不需包含 @ 符號。</li>

  <li>
    `x` 與 `y` 必須是浮點數，以圖片左上角為原點，範圍為 `0.0`–`1.0`。僅適用於
    單張圖片。Reel 上不要包含這兩個值，否則會發生錯誤。
  </li>
</ul>

```json Instagram User Tags theme={"system"}
{
  "instagramOptions": {
    "userTags": [
      {
        "username": "ayrshare", // Required: Instagram username
        "x": 0.5, // Required for Images, cannot be used with Reels
        "y": 1.0 // Required for Images, cannot be used with Reels
      },
      {
        "username": "johnboy", // Required: Instagram username
        "x": 0.1, // Required for Images, cannot be used with Reels
        "y": 0.9 // Required for Images, cannot be used with Reels
      }
    ]
  }
}
```

## Instagram 提及

在貼文文字中加入 @handle 即可提及其他 Instagram 使用者。

例如你可以在貼文文字中提及 @ayrshare handle：

```json Instagram Mentions theme={"system"}
{
  "post": "The best social media API @Ayrshare ever!", // empty string is allowed
  "mediaUrls": ["https://images.com/image.jpg"],
  "platforms": ["instagram"]
}
```

<Warning>
  被 `@提及` 的使用者會收到通知。請詳閱關於提及功能的
  [重要規則](/testing/post-verification#mentions)。
</Warning>

## 共同創作

Instagram 共同創作功能讓你可以透過 [將他人標註為 collaborator](https://www.facebook.com/help/instagram/291200585956732) 與其他 Instagram 帳號共同創作內容。
這讓你可以將其他 Instagram 使用者指定為該貼文的創作者。
被標註後，這些使用者會在行動 App 中收到共同創作邀請。
若他們接受，該貼文也會出現在他們的動態消息，並讓其追蹤者看得到，進一步擴大貼文的觸及與互動潛力。

### Collaborators

公開的原始作者可以將其他公開帳號標註為 Instagram collaborator。
另一個帳號會收到訊息，可以選擇接受或拒絕該邀請。
若對方接受，該貼文也會顯示在其個人檔案上，並在 Instagram 動態消息中散布給其追蹤者。
貼文標題會標示該內容由兩個帳號共同創作。

你可以在 Reel、圖片或輪播上加入 collaborators。

透過 Instagram API 無法標註私人 collaborator。雖然
Instagram App 內有此功能，但平台與其 API 通常不會 [功能對等](/help-center/product/are_social_networks_native_apps_and_the_apis_at_parity)。

<Warning>Instagram Stories 不支援 collaborators。</Warning>

<Warning>
  <ul class="custom-bullets">
    <li>**只邀請你預期會 `accept` 你邀請的 collaborators**。</li>

    <li>
      如果 [collaborator
      回覆](/apis/post/social-networks/instagram#get-collaborator-request-status) 為
      `declined` 的共同創作請求，**在你聯絡他們了解拒絕原因之前，
      請勿再次邀請他們**。
    </li>

    <li>
      同一或多位使用者反覆拒絕，會讓你的 Instagram 與 Ayrshare
      帳號面臨被停用的風險。
    </li>

    <li>原始作者可以隨時新增或移除 collaborator。</li>
  </ul>
</Warning>

以公開的 Instagram username 陣列邀請 *最多三位* collaborators。

```json Instagram Collaborators theme={"system"}
{
  "instagramOptions": {
    "collaborators": ["ayrshare", "therock", "taylorswift"] // Up to three
  }
}
```

這三位 collaborators 會在其 Instagram 行動 App 中收到訊息邀請，可以接受或拒絕。之後你可以 [檢查被邀請使用者的請求狀態](/apis/post/social-networks/instagram#get-collaborator-request-status)。
請只邀請你確定會接受的 collaborator，否則你的 Instagram 帳號可能會受到負面影響。

<Warning>
  關於被邀請 collaborator 的備註：除了少數例外，共同創作媒體的相關資料只能由
  發布該媒體的使用者透過 API 存取；collaborators 無法透過
  API 存取這些資料。
</Warning>

### 取得 Collaborator 請求狀態

邀請 Instagram collaborator 之後，可以使用 [Get Collaborator Request Status API](/apis/utils/instagram-get-collaborator) 檢查該請求的狀態。

## 自動圖片縮放

<Note>需要 Max Pack</Note>

透過 `autoResize` 參數，可以自動將圖片縮放為 1080 x 1080 px 以符合 Instagram。請注意，這會將圖片同時縮放給所有包含的平台，因此建議另外對 Instagram 呼叫一次 /post，並對其他平台各別呼叫。

```json Instagram Auto Image Resize theme={"system"}
{
  "post": "Let it go!",
  "platforms": ["instagram"],
  "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"],
  "instagramOptions": {
    "autoResize": true, // Max Pack
    "locationId": 7640348500,
    "userTags": [
      {
        "username": "ayrshare",
        "x": 0.5,
        "y": 0.5
      },
      {
        "username": "ayrshare",
        "x": 0.3,
        "y": 0.2
      }
    ]
  }
}
```

## 已用配額

Instagram 回應會包含目前的 `usedQuota`，即滾動 24 小時內已完成的 Instagram 貼文數量。Instagram 在滾動 24 小時內只允許 50 則貼文。

```json Instagram Used Quota theme={"system"}
{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "17823977408036085",
            "postUrl": "https://www.instagram.com/p/CeBrkQuN1Kv/",
            "usedQuota": 15,
            "platform": "instagram"
        }
    ],
    "id": "l4FaPHSXWJNdmMfm3dIE",
    "refId": "65806e8d9efd78a58c05566a887043329dcdc76b",
    "post": "Luckily for Alice, the little magic bottle had now had its full effect."
}
```

如果配額已達上限，會回傳錯誤訊息。

## 內容問題

Ayrshare 內建媒體保護機制，可在發布過程中偵測並解決特定的媒體傳輸問題。當貼文成功發布，但過程中偵測並解決了某項內容問題時，回應中會包含選用的 `contentIssues` 物件。這讓你可以主動識別並修正媒體託管的問題。

`contentIssues` 物件僅在偵測到並解決了問題時才會出現 — 一般成功發布的貼文不會包含此欄位。

| 欄位                      | 型別        | 說明                                                                                                                                                                 |
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `originMediaHostFailed` | boolean   | 社群網路無法從提供的 URL 擷取媒體。Ayrshare 的自動媒體保護解決了該問題，並成功完成發布。建議檢查你的媒體託管設定 — 常見原因請參閱 [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked)。 |
| `details`               | string 陣列 | 各偵測到的問題的人類可讀說明。                                                                                                                                                    |

```json Content Issues Response Example theme={"system"}
{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "17878176260289172",
            "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
            "usedQuota": 12,
            "platform": "instagram",
            "contentIssues": {
                "originMediaHostFailed": true,
                "details": [
                    "Media URL could not be retrieved by the social network. Successfully posted using Ayrshare automated media protection."
                ]
            }
        }
    ],
    "id": "abc123",
    "refId": "65806e8d9efd78a58c05566a887043329dcdc76b",
    "post": "Your post text here"
}
```

<Tip>
  如果你在回應中看到 `originMediaHostFailed`，可能是你的媒體託管有問題，導致社群網路無法存取你的媒體。詳細的疑難排解步驟請參閱 [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked)。
</Tip>

## 錯誤細節

<Info>
  當 Instagram 媒體發布失敗時，錯誤物件現在會在 `details` 欄位中呈現 Meta 底層的錯誤文字，並同時提供 Ayrshare 的 `code` 與 `message`。這讓你可以在不需聯絡客服的情況下區分不同的根本原因（例如長寬比被拒絕與媒體下載失敗）。
</Info>

```json Instagram Publish Error theme={"system"}
{
    "status": "error",
    "errors": [
        {
            "action": "post",
            "status": "error",
            "platform": "instagram",
            "code": 156,
            "message": "An error occurred while posting to Instagram.",
            "details": "The submitted image was not found. The aspect ratio is not supported. Please see https://developers.facebook.com/docs/instagram-api for more information."
        }
    ]
}
```

`message` 是 Ayrshare 提供的穩定、人類可讀摘要，而 `details` 則直接回傳 Meta 對該次失敗發布傳回的原始文字。

## 在 Instagram 貼文中加入換行或 rich text

Instagram 貼文中的換行可以使用特殊的[換行字元](/apis/post/post#line-breaks)加入。

Rich text（例如粗體或斜體）可以透過幾個 [HTML 元素](/apis/post/overview#rich-text-posts) 加到 Instagram 貼文中。

## 字元限制

更多資訊請參閱 [Instagram 字元限制](/help-center/technical-support/character_limits#instagram-character-limits)。

## 其他端點

<Card title="取得 Collaborator 請求狀態" icon="code" href="/apis/utils/instagram-get-collaborator" horizontal />