內容發佈

您可以使用 Instagram Graph API 在 Instagram 專業帳戶上發佈單一圖片、影片、連續短片（即單一媒體帖子）或包含多項圖片與影片的帖子（輪播帖子）。

由 2023 年 7 月 1 日起，透過 Instagram 內容發佈 API 發佈的所有單一動態消息影片均會以連續短片形式分享。

必要條件

存取憑證

所有要求必須包括應用程式用戶的用戶存取憑證。

權限

發佈操作需要取得以下權限組合。具體所需組合視乎您應用程式使用的端點而定。請參閱我們的端點參考資料，以確定每個端點需要哪些權限。

如果您的應用程式將供沒有角色的用戶使用，則您必須先透過應用程式審查為每項權限提出批准要求，然後這些用戶才能向您的應用程式授予權限；沒有角色的應用程式用戶即在您應用程式中沒有任何角色的用戶，或於已認領您應用程式的企業中沒有角色的用戶。

公共伺服器

我們會對用戶嘗試發佈內容中所用的媒體執行 cURL 要求，因此在您嘗試發佈時，該媒體必須在公共伺服器上託管。

專頁發佈授權

如果與 Instagram 專業帳戶連結的專頁需要專頁發佈授權（PPA），則必須完成此授權，否則將無法發佈內容。

應用程式用戶或可在一開始不需要 PPA 的專頁上執行任務，但此專頁之後有可能需要 PPA。在這種情況下，應用程式用戶在完成 PPA 前將無法發佈內容至其 Instagram 專業帳戶。由於您無法確定應用程式用戶的專頁是否需要專頁發佈授權，我們建議您告知應用程式用戶預先完成這項授權。

限制

只支援 JPEG 這種圖片格式，不支援 MPO 和 JPS 等 JPEG 延伸格式。
不支援購物標籤。
不支援品牌置入內容標籤。
不支援濾鏡。
不支援發佈至 Instagram TV。

如需了解其他限制，請參閱各端點的參考資料。

限速

Instagram 帳戶只可每連續 24 小時內透過 API 發佈 50 則帖子。輪播內容算作單則帖子。在嘗試發佈媒體容器時，此限制會在 POST /{ig-user-id}/media_publish 端點上執行。我們建議您的應用程式同樣執行發佈限速限制，尤其當您的應用程式允許應用程式用戶安排在未來特定時間發佈帖子時更是如此。

如要查看 Instagram 專業帳戶目前的限速限制使用情況，請查詢 GET /{ig-user-id}/content_publishing_limit 端點。

端點

此 API 由以下端點組成。請參閱每個端點的參考文件以了解使用要求。

POST /{ig-user-id}/media — 上載媒體並建立媒體容器。
POST /{ig-user-id}/media_publish — 以其媒體物件容器發佈已上載的媒體。
GET /{ig-container-id}?fields=status_code — 檢查媒體容器的發佈資格和狀態。
GET /{ig-user-id}/content_publishing_limit — 檢查應用程式用戶目前的發佈限速使用量。

單一媒體帖子

發佈單一圖片、影片、限時動態或連續短片的操作可分為兩個步驟：

使用 POST /{ig-user-id}/media 端點，透過在公共伺服器上託管的圖片或影片建立容器。
使用 POST /{ig-user-id}/media_publish 端點發佈該容器。

步驟 2 之 1：建立容器

舉例來說，假設您想要發佈位於以下網址的圖片：

https://www.example.com/images/bronz-fonz.jpg

而且想加上「#BronzFonz」主題標籤作為其說明文字。您可以向 POST /{ig-user-id}/media 端點傳送要求：

要求範例

POST https://graph.facebook.com/v20.0/17841400008460056/media
  ?image_url=https://www.example.com/images/bronz-fonz.jpg
  &caption=#BronzFonz

此操作將傳回圖片的容器編號。

回應範例

{
  "id": "17889455560051444"  // IG Container ID
}

步驟 2 之 2：發佈容器

使用 POST /{ig-user-id}/media_publish 端點來發佈在上一步驟中傳回的容器編號。

要求範例

POST https://graph.facebook.com/v20.0/17841400008460056/media_publish ?creation_id=17889455560051444

回應範例

{
  "id": "17920238422030506" // IG Media ID
}

輪播帖子

在單一輪播帖子中，您可以發佈最多 10 項圖片和／或影片。發佈輪播帖子分為 3 個步驟：

使用 POST /{ig-user-id}/media 端點，為將會在輪播帖子中出現的每項圖片和影片建立單獨的項目容器。
再次使用 POST /{ig-user-id}/media 端點，為相關項目建立單一輪播容器。
使用 POST /{ig-user-id}/media_publish 端點來發佈輪播容器。

在帳戶限速中，輪播帖子算作單則帖子。

限制

輪播帖子無法加強推廣。
輪播帖子的圖片和／或影片總數不得超過 10 項。
系統會根據輪播帖子中的第一張圖片裁剪輪播帖子中的所有圖片，預設長闊比例為 1:1。

步驟 3 之 1：建立項目容器

使用 POST /{ig-user-id}/media 端點，為將會在輪播帖子中出現的圖片或影片建立項目容器。輪播帖子最多可包含 10 項圖片和／或影片。

POST /{ig-user-id}/media

參數

以下參數為必要項目。如需了解其他支援的參數，請參閱 POST /{ig-user-id}/media 端點參考資料。

is_carousel_item：設為 true。表示輪播帖子中會出現圖片或影片。
image_url：（僅限圖片）圖片的路徑。我們會使用傳入的網址來為圖片執行 cURL 要求，因此該圖片必須在公共伺服器上託管。
media_type：（僅限影片）設為 VIDEO。表示媒體為影片。
video_url：（僅限影片）影片的路徑。我們會使用傳入的網址來為影片執行 cURL 要求，因此該影片必須在公共伺服器上託管。

如果操作成功，API 將傳回一個項目容器編號，該編號可被用來建立輪播容器。

為應該出現在輪播帖子中的每項圖片或影片重複此程序。

要求範例

curl -i -X POST \

"https://graph.facebook.com/v20.0/90010177253934/media?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=EAAOc..."

回應範例

{
  "id": "17899506308402767"
}

步驟 3 之 2：建立輪播容器

使用 POST /{ig-user-id}/media 端點來建立輪播容器。

POST /{ig-user-id}/media

參數

以下參數為必要項目。如需了解其他支援的參數，請參閱 POST /{ig-user-id}/media 端點參考資料。

media_type：設為 CAROUSEL。表示容器用於輪播帖子。
children：包含多達 10 個容器編號的陣列；這些編號對應每項應該顯示在所發佈之輪播帖子上的圖片和影片。輪播帖子最多可包含 10 項圖片和／或影片。

要求範例

curl -i -X POST \

"https://graph.facebook.com/v20.0/90010177253934/media?caption=Fruit%20candies&media_type=CAROUSEL&children=17899506308402767%2C18193870522147812%2C17853844403701904&access_token=EAAOc..."

回應範例

{
  "id": "18000748627392977"
}

步驟 3 之 3：發佈輪播容器

使用 POST /{ig-user-id}/media_publish 端點，以發佈輪播容器（輪播帖子）。每個帳戶只可在 24 小時內發佈 50 則帖子。發佈的輪播內容會算作單則帖子。

POST /{ig-user-id}/media_publish

參數

以下參數為必要項目。

creation_id：輪播容器編號。

如果操作成功，API 將傳回一個輪播相簿 Instagram 媒體編號。

要求範例

curl -i -X POST \

"https://graph.facebook.com/v20.0/90010177253934/media_publish?creation_id=18000748627392977&access_token=EAAOc..."

回應範例

{
  "id": "90010778390276"
}

連續短片帖子

連續短片是指可顯示在 Instagram 應用程式「Reels」分頁的合資格短片，這類影片必須符合特定規格，且被我們的演算法選中。如要發佈連續短片，請按照發佈單一媒體帖子的步驟操作，並使用 video_url 參數在影片路徑中加入 media_type=REELS 參數。

雖然您在發佈連續短片時需要設定 media_type=REELS，但連續短片並非新的媒體類型。如果您發佈連續短片，然後要求獲取其 media_type 欄位，則系統傳回的值為 VIDEO。如要確定是否已將所發佈的影片指定為連續短片，請改為要求獲取其 media_product_type 欄位。

您可以使用 GitHub 上的程式碼範例（insta_reels_publishing_api_sample），了解如何將 Reels 發佈至 Instagram。

為了方便開發人員操作，Meta 在 Postman API 平台上發佈了一整套 Instagram Reels 專用的 Graph API 呼叫。詳情請參閱 Facebook Reels 和 Instagram Reels 專用的 Postman 收藏集。

如要進一步了解 Reels 連續短片，請參閱連續短片開發人員文件。

限時動態帖子

目前，只有商業帳戶可以使用 Content Publising API 發佈限時動態。

限時動態是指在 Instagram 上以 Instagram 限時動態形式發佈的影片和圖片。如要發佈限時動態，請按照與發佈單一媒體帖子相同的步驟操作，並使用 image_url 或 video_url 參數在圖片／影片路徑中加入 media_type=STORIES 參數。

備註：雖然您在發佈限時動態時需要設定 media_type=STORIES，但限時動態並非新的媒體類型。如果您發佈限時動態，然後要求其 media_type 欄位，系統會傳回的值為 IMAGE/VIDEO。如要確定是否已將所發佈的圖片／影片指定為限時動態，請改為要求獲取其 media_product_type 欄位。

可恢復的上載通訊協定

可恢復的上載通訊協定是發佈 Instagram 內容的全新流程，支援 Reels、影片限時動態和影片輪播項目 media_types 的影片上載。

這個新通訊協定同時支援從本機影片和公共託管網址影片建立 Instagram 媒體。此協定可讓您在網絡中斷或出現其他傳輸故障後恢復本機檔案上載操作，從而在網絡故障時節省時間和頻寬。它保留相同的媒體規格。

端點

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media—透過設定 upload_type=resumable 初始化影片建立容器。
POST https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}—使用可恢復的上載通訊協定，更可靠地從本機影片檔案或託管網址上載影片。
POST https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish—以其媒體物件容器發佈已上載的媒體。
GET /{ig-container-id}?fields=status_code—檢查媒體容器的發佈資格和狀態。

HTML 網址編碼提示

部分參數支援清單／字典格式。
有些字元需要編碼至可以透過互聯網傳輸的格式。例如：user_tags=[{username:’ig_user_name’}] 編碼為 user_tags=%5B%7Busername:ig_user_name%7D%5D，其中 [ 編碼為 %5B，{ 編碼為 %7B。如需更多轉換資訊，請參考 HTML 網址編碼標準。

第 1 步：初始化 Reels、影片限時動態或輪播項目的上載連線階段

Reels 要求範例

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=REELS" \
    -d "upload_type=resumable" \
    -d "caption={caption}"\
    -d "collaborators={collaborators-username}"
    -d "cover_url={cover-url}" \
    -d "audio_name={audio-name}" \
    -d "user_tags={user-tags}" \
    -d "location_id={location-id}" \
    -d "thumb_offset={thumb-offset}" \
    -H "Authorization: OAuth {access-token}"

影片限時動態要求範例

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=STORIES" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

輪播影片項目要求範例

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=VIDEO" \
    -d "is_carousel_item=true" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

回應範例

{
   "id": "{ig-container-id}",
   "uri": "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}"
}

第 2 步：使用可恢復的上載通訊協定上載影片

大多數 Graph API 呼叫使用 graph.facebook.com 主機，但為 Reels 上載影片的呼叫則使用 rupload.facebook.com。

上載的影片檔案支援以下檔案來源：

您電腦上的檔案
託管在公開伺服器（如 CDN）上的檔案

上載本機影片檔案要求範例

使用可恢復的上載連線階段呼叫傳回的 ig-container-id 來上載影片。

確保主機是 rupload.facebook.com。
所有 media_type 的上載影片流程都相同。
ig-container-id 是從可恢復的上載連線階段呼叫傳回的 ID。
access-token 與先前步驟中使用的存取憑證相同。
offset 設定為上載的第一個位元組，一般為 0。
file_size 設定為檔案的大小，以位元組為單位。
Your_file_local_path 設定為本機檔案的檔案路徑。例如，如果從 macOS 上的「下載項目」資料夾上載檔案，則路徑為 @Downloads/example.mov。

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@my_video_file.mp4"

上載公開託管影片要求範例

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "file_url: https://example_hosted_video.com"

回應範例

// Success Response Message
{
  "success":true,
  "message":"Upload successful."
}

// Failure Response Message
{
  "debug_info":{
    "retriable":false,
    "type":"ProcessingFailedError",
    "message":"{\"success\":false,\"error\":{\"message\":\"unauthorized user request\"}}"
  }
}

第 3 步：（僅限輪播項目）建立輪播容器

您可以重複執行第 1 步和第 2 步來建立多個 ig-container-ids，並將 is_carousel_item 參數設為 true。然後，建立輪播容器來加入所有輪播項目；輪播項目可以與圖片和影片配搭使用。

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=CAROUSEL" \
    -d "caption={caption}"\
    -d "collaborators={collaborator-usernames}" \
    -d "location_id={location-id}" \
    -d "product_tags={product-tags}" \
    -d "children=[{ig-container-id},{ig-container-id}...]" \
    -H "Authorization: OAuth {access-token}"

第 4 步：發佈媒體

對於 Reels 和影片限時動態，在第 1 步中建立的 {ig-container-id}用於發佈影片；對於輪播容器，在第 3 步中建立的 {ig-container-id} 用於發佈輪播容器。

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish" \
    -d "creation_id={ig-container-id}" \
    -H "Authorization: OAuth {access-token}"

第 5 步：取得媒體狀態

graph.facebook.com 提供了 GET 端點來讀取上載狀態，video_status 欄位包含有關本機上載過程的詳細資料。

uploading_phase 說明檔案是否已成功上載，以及傳輸了多少位元組。
processing_phase 包含上載影片檔案後的影片處理狀態詳細資料。

// GET status from graph.facebook.com
curl -X GET "https://graph.facebook.com/v19.0/{ig-container-id}?fields=id,status,status_code,video_status" \
    -H "Authorization: OAuth {access-token}"

來自 `graph.facebook.com` 端點的回應範例

// A successfully created ig container
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "complete",
      "bytes_transferred": 37006904
    },
    "processing_phase": {
      "status": "complete"
    }
  }
}

// An interrupted ig container creation, from here you can resume your upload in step 2 with offset=50002. 
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "in_progress",
      "bytes_transferred": 50002
    },
    "processing_phase": {
      "status": "not_started"
    }
  }
}

協作者標籤

您可以將公開的 Instagram 用戶加為圖片、輪播內容和連續短片的協作者，有關用戶即會收到邀請成為此特定媒體的協作者。如需在圖片中標註用戶，請按照以上單一媒體帖子的步驟操作，但您要在建立媒體容器時加入協作者參數和字串陣列，以註明您想邀請作為媒體協作者的 Instagram 用戶之用戶名稱。

要求範例

POST graph.facebook.com/17841400008460056/media
?image_url=https://www.example.com/images/bronzed-fonzes.jpg
&caption=#BronzedFonzes!
&collaborators= [‘username1’,��username2’]

備註

協作者值必須為字串陣列。
您只能標註 Instagram 帳戶設為公開的用戶。
每個媒體最多只能加入 3 個協作者。
不能在限時動態媒體加入協作者。

地點標籤

您可以使用專頁搜尋 API 搜尋名稱與搜尋字串配對的專頁。搜尋時，請確保在查詢中加入「位置」欄位。然後，剖析搜尋結果，以找出任何為實體位置建立的專頁。如果您在發佈圖片或影片時加入專頁的編號，則相關項目將被標註與該專頁相關的位置。

限制

如要符合標註條件，專頁必須擁有包含經緯度的位置資料。

在您要使用的專頁，確認回應中是否包含經緯度資料。如果您嘗試使用不具備地點資料的專頁建立容器，操作將會失敗並傳回例外情況程式碼 INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID。

獲得專頁編號後，請在發佈單一媒體或輪播項目容器時將該編號分配給 location_id 參數。

商品標籤

您可以發佈帶有 Instagram 購物功能商品標籤的單一媒體帖子和輪播帖子。請參閱商品標註功能指南以了解如何操作。

用戶標籤

您可以在圖片中標註公開的 Instagram 用戶，他們會在被標註時收到通知。

如需在圖片中標註用戶，請按照以上單一媒體帖子的步驟操作，但您要在建立媒體容器時加入 user_tags 參數和物件陣列，以註明圖片中的 Instagram 用戶及其在圖片中的 x/y 座標。

要求範例

POST graph.facebook.com/17841400008460056/media ?image_url=https://www.example.com/images/bronzed-fonzes.jpg &caption=#BronzedFonzes! &user_tags= [ { username:'kevinhart4real', x: 0.5, y: 0.8 }, { username:'therock', x: 0.3, y: 0.2 } ]

此操作將傳回一個容器編號，然後您可以使用 Instagram 用戶媒體發佈端點發佈該編號。

備註

user_tags 值必須為 JSON 格式的物件陣列。
您只能標註 Instagram 帳戶設為公開的用戶。
物件必須包含每位用戶的所有三個屬性（username、x 和 y）。
x 和 y 值必須為源自圖片左上方的 float 數值，範圍為 0.0–1.0。
用戶標籤可用於輪播項目中的圖片。

疑難排解

如果您能夠為影片建立容器，但 POST /{ig-user-id}/media_publish 端點並未傳回已發佈的媒體編號，則可以透過查詢 GET /{ig-container-id}?fields=status_code 端點獲取容器發佈狀態。此端點將會傳回以下其中一種狀態：

EXPIRED — 容器未在 24 小時內發佈，已過期。
ERROR—容器無法完成發佈程序。
FINISHED—已準備好發佈容器及其媒體物件。
IN_PROGRESS—容器仍處於發佈階段。
PUBLISHED — 已發佈容器的媒體物件。

我們建議每分鐘查詢一次容器狀態，查詢時間不應超過 5 分鐘。

錯誤

請查看錯誤代碼參考文件。

內容發佈

必要條件

存取憑證

權限

公共伺服器

專頁發佈授權

限制

限速

端點

單一媒體帖子

要求範例

回應範例

要求範例

回應範例

輪播帖子

參數

要求範例

回應範例

參數

要求範例

回應範例

參數

要求範例

回應範例

連續短片帖子

限時動態帖子

可恢復的上載通訊協定

端點

HTML 網址編碼提示

第 1 步：初始化 Reels、影片限時動態或輪播項目的上載連線階段

Reels 要求範例

影片限時動態要求範例

輪播影片項目要求範例

回應範例

第 2 步：使用可恢復的上載通訊協定上載影片

上載本機影片檔案要求範例

上載公開託管影片要求範例

回應範例

第 3 步：（僅限輪播項目）建立輪播容器

第 4 步：發佈媒體

第 5 步：取得媒體狀態

來自 graph.facebook.com 端點的回應範例

協作者標籤

要求範例

備註

地點標籤

限制

商品標籤

用戶標籤

要求範例

備註

疑難排解

錯誤

來自 `graph.facebook.com` 端點的回應範例