內容發佈

您可以使用 Instagram 圖形 API，在 Instagram 專業帳號上發佈單一圖像、影片、連續短片（即單一影音素材貼文），或包含多個圖像的貼文、影片（輪播廣告貼文）。

從 2023 年 7 月 1 日開始，所有透過 Instagram 內容發佈 API 發佈的單一動態消息影片都將以連續短片形式分享。

必備條件

存取權杖

所有要求必須包含應用程式用戶的用戶存取權杖。

權限

發佈是根據以下權限的組合，確切的組合則取決於應用程式使用的端點。請參閱端點參考資料，以確定每個端點所需的權限。

如果有不具應用程式角色，或不具企業角色但自稱是應用程式擁有者的應用程式用戶會使用您的應用程式，您必須先透過應用程式審查要求核准每個權限，非角色應用程式用戶才能將其授予您的應用程式。

公開伺服器

我們會為在發佈嘗試中使用的影音素材建立 cURL，因此在進行嘗試時，影音素材必須裝載在可公開存取的伺服器上。

粉絲專頁發佈授權

必須等到需要粉絲專頁發佈授權（PPA）的粉絲專頁完成 PPA 之後，才能發佈內容到與其連線的 Instagram 專業帳號。

應用程式用戶可能在最初不需要 PPA，但在後來需要的粉絲專頁上執行工作。在此情況下，應用程式用戶必須等到完成 PPA 之後，才能將內容發佈到其 Instagram 專業帳號。由於無法確定應用程式用戶的粉絲專頁是否需要 PPA，您可以建議應用程式用戶預先完成 PPA。

限制

JPEG 是唯一支援的圖像格式。不支援延伸的 JPEG 格式，例如 MPO 和 JPS。
不支援購物標籤。
不支援品牌置入內容標籤。
不支援篩選條件。
不支援發佈至 Instagram TV。

其他限制請參閱每個端點的參考資料。

速率限制

Instagram 帳號限制在 24 小時的移動期間內只能發佈 50 篇 API 貼文。輪播廣告計為單一貼文。當嘗試發佈影音素材容器時，此限制會在 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 端點發佈該容器。

步驟 1／2：建立容器

假設有一個圖像位於⋯⋯

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 個圖像、影片或兩者的混合。發佈輪播廣告的程序包含三個步驟：

使用 POST /{ig-user-id}/media 端點為將顯示在輪播廣告中的每個圖像和影片建立個別的項目容器。
再次使用 POST /{ig-user-id}/media 端點建立內容的單一輪播廣告容器。
使用 POST /{ig-user-id}/media_publish 端點發佈輪播廣告容器。

輪播廣告貼文對帳號的限速而言是計為單一貼文。

限制

您無法加強推廣輪播廣告。
輪播廣告限制為 10 個圖像、影片或兩者的混合。
輪播廣告的圖像會根據輪播廣告中的第一個圖像來全部進行裁切，而預設的長寬比為 1：1。

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

使用 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"
}

步驟 2／3：建立輪播廣告容器

使用 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 將傳回輪播廣告相簿 IG 影音素材編號。

要求範例

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）來瞭解如何在 Instagram 上發佈 Reels。

為了方便開發人員，Meta 已在 Postman API 平台上發佈 Instagram Reels 的全套圖形 API 呼叫。如需詳細資訊，請參閱 Facebook Reels 和 Instagram Reels 的 Postman 集合。

如需 Reels 的詳細資訊，請參閱 Reels 開發人員文件。

限時動態貼文

目前只有商業帳號可以使用內容發佈 API 發佈限時動態。

限時動態是發佈在 Instagram 上作為 IG 限時動態的影片和圖像。若要發佈限時動態，請按照發佈單一影音素材貼文的步驟操作，並使用 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：使用可續傳的上傳通訊協定上傳影片

大多數圖形 API 呼叫採用 graph.facebook.com 主機，然而 Reels 上傳影片的呼叫則採用 rupload.facebook.com。

上傳的影片檔案可採用以下檔案來源：

位於您電腦中的檔案
託管於公開伺服器（例如 CDN）的檔案

上傳本機影片檔要求範例

在可續傳的上傳連線階段呼叫傳回 ig-container-id 時，上傳影片。

注意主機應為 rupload.facebook.com。
所有 media_type 上傳影片的流程均相同。
ig-container-id 是可續傳的上傳連線階段呼叫所傳回的編號。
access-token 與上一個步驟所用的相同。
offset 設為上傳的第一個位元組，通常是 0。
file_size 設為檔案的大小（以位元組為單位）。
Your_file_local_path 設為本機檔案的檔案路徑。例如，由 macOS 的 Downloads 資料夾上傳檔案時，路徑為 @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 來搜尋名稱與搜尋字串相符的粉絲專頁（請務必在查詢中包含「location」欄位），然後剖析結果，以識別已經為實體地點建立的任何粉絲專頁。如果您在發佈圖像或影片時包含粉絲專頁的編號，系統會將圖像或影片與該粉絲專頁相關聯的地點標註在一起。

限制

若要符合標註的條件，粉絲專頁必須具有緯度和經度地點資料。

驗證您想要使用的粉絲專頁在回應中具有緯度和經度資料。若嘗試使用不具地點資料的粉絲專頁建立容器，將會失敗，例外狀況代碼為 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 } ]

如此會傳回容器編號，然後您就可以使用 IG 用戶影音素材發佈端點進行發佈。

備註

user_tags 值必須為 JSON 格式的物件陣列。
您只能標註使用公開 Instagram 帳號的用戶。
物件必須包含每個用戶的所有三個屬性（username、x 和 y）。
x 和 y 的值必須為從圖像左上角開始，範圍介於 0.0 至 1.0 的 float 數。
用戶標籤可與輪播廣告中的圖像搭配使用。

疑難排解

如果您能夠為影片建立容器，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` 端點的回應範例