您可以使用 Instagram 圖形 API,在 Instagram 專業帳號上發佈單一圖像、影片、連續短片(即單一影音素材貼文),或包含多個圖像的貼文、影片(輪播廣告貼文)。
從 2023 年 7 月 1 日開始,所有透過 Instagram 內容發佈 API 發佈的單一動態消息影片都將以連續短片形式分享。
所有要求必須包含應用程式用戶的用戶存取權杖。
發佈是根據以下權限的組合,確切的組合則取決於應用程式使用的端點。請參閱端點參考資料,以確定每個端點所需的權限。
如果有不具應用程式角色,或不具企業角色但自稱是應用程式擁有者的應用程式用戶會使用您的應用程式,您必須先透過應用程式審查要求核准每個權限,非角色應用程式用戶才能將其授予您的應用程式。
我們會為在發佈嘗試中使用的影音素材建立 cURL,因此在進行嘗試時,影音素材必須裝載在可公開存取的伺服器上。
必須等到需要粉絲專頁發佈授權(PPA)的粉絲專頁完成 PPA 之後,才能發佈內容到與其連線的 Instagram 專業帳號。
應用程式用戶可能在最初不需要 PPA,但在後來需要的粉絲專頁上執行工作。在此情況下,應用程式用戶必須等到完成 PPA 之後,才能將內容發佈到其 Instagram 專業帳號。由於無法確定應用程式用戶的粉絲專頁是否需要 PPA,您可以建議應用程式用戶預先完成 PPA。
其他限制請參閱每個端點的參考資料。
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/v19.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/v19.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
端點發佈輪播廣告容器。輪播廣告貼文對帳號的限速而言是計為單一貼文。
限制
步驟 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/v19.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/v19.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/v19.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 用戶新增為協作者,他們將收到邀請成為該特定影音素材的協作者。若要在圖像中標註用戶,請按照上述「單一影音素材貼文」的步驟操作,但在建立影音素材容器時,請包含協作者參數和指示用戶之 Instagram 用戶名稱的字串陣列,這些是您希望邀請作為影音素材協作者的用戶。
POST graph.facebook.com/17841400008460056/media ?image_url=https://www.example.com/images/bronzed-fonzes.jpg &caption=#BronzedFonzes! &collaborators= [‘username1’,’username2’]
您可以使用粉絲專頁搜尋 API 來搜尋名稱與搜尋字串相符的粉絲專頁(請務必在查詢中包含「location」欄位),然後剖析結果,以識別已經為實體地點建立的任何粉絲專頁。如果您在發佈圖像或影片時包含粉絲專頁的編號,系統會將圖像或影片與該粉絲專頁相關聯的地點標註在一起。
若要符合標註的條件,粉絲專頁必須具有緯度和經度地點資料。
驗證您想要使用的粉絲專頁在回應中具有緯度和經度資料。若嘗試使用不具地點資料的粉絲專頁建立容器,將會失敗,例外狀況代碼為 INSTAGRAM_PLATFORM_API__INVALID_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 格式的物件陣列。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 分鐘。
請參閱錯誤代碼參考資料。