Instagram 開放平台
返回中文(台灣)
這份文件已更新。
中文(台灣) 的翻譯尚未完成。
英文更新時間：9月3日

IG 影音素材

代表 Instagram 相簿、相片或影片（上傳的影片、直播影片、使用 Instagram TV 應用程式建立的影片、連續短片或限時動態）。

從 2024 年 6 月 3 日開始，您可以使用 boost_eligibility_info 欄位，輕鬆快速地判斷影音素材是否符合資格，可以當作廣告加強推廣，並使用 boost_ads_list 追蹤過去加強推廣的廣告相關 Instagram 廣告資訊。詳情請參閱此部落格。僅開放 Instagram 圖形 API 使用。

建立

不支援執行此作業。

讀取

GET /<IG_MEDIA_ID>

取得 IG 影音素材的欄位和關係連線。

限制

  • 回傳彙總值的欄位不包含廣告驅動的資料。例如，comments_count 會計算相片的留言數，但不會計算包含該相片之廣告的留言數。
  • 說明文字不包含 @ 符號，除非應用程式用戶也能在應用程式上執行管理員層級的任務。
  • 某些欄位（例如 permalink）無法用於相簿內的相片（子項）。
  • 您只能在直播進行時讀取直播影片 IG 影音素材。
  • 此 API 僅傳回 Instagram 專業帳號所擁有的影音素材資料，不可用於取得個人 Instagram 帳號所擁有的影音素材資料。

要求語法

GET https://graph.facebook.com/<API_VERSION>/<IG_MEDIA_ID>
  ?fields=<LIST_OF_FIELDS>
  &access_token=<ACCESS_TOKEN>

路徑參數

預留位置值

<API_VERSION>

API 版本。

<IG_MEDIA_ID>

必要項目。要發佈的影音素材編號。

查詢字串參數

索引鍵預留位置值

access_token

<ACCESS_TOKEN>

必要項目。應用程式用戶的用戶存取權杖

fields

<LIST_OF_FIELDS>

您想傳回的欄位逗號分隔清單。

欄位

可透過欄位擴充讀取公開欄位。

欄位說明

boost_ads_list

提供與自主影音素材相關聯的所有 Instagram 廣告資訊總覽，包括相關的廣告編號和廣告投遞狀態。僅開放 Instagram 圖形 API 使用。

boost_eligibility_info

此欄位提供使用 IG Instagram 影音素材做為廣告的加強推廣資格相關資訊，以及不符合資格時的其他詳細資訊。僅開放 Instagram 圖形 API 使用。

caption
公開

說明文字。不含相簿子項。不含 @ 符號，除非應用程式用戶可以在 Facebook 粉絲專頁執行管理員層級的任務，且該粉絲專頁連結到用於建立說明文字的 Instagram 帳號（僅限 Instagram 圖形 API）。

comments_count
公開

影音素材的留言數。不含相簿子影音內容和影音內容描述的留言。包含對留言的回覆次數。

copyright_check_information.status

傳回 status 和 matches_found 物件

status 物件說明

status

  • completed – 偵測程序已完成
  • error – 偵測程序期間發生錯誤
  • in_progress – 偵測程序進行中
  • not_started – 偵測程序尚未開始

matches_found

設定為下列其中一項：

  • 如果影片未侵犯著作權，則設為 false
  • 如果影片侵犯著作權，則設為 true

如果影片侵犯著作權，系統會傳回 copyright_matches 和一個物件陣列，內容包括受著作權保護的素材、影片中發生違規行為的時間，以及緩解違規行為所需採取的措施。

copyright_matches 物件說明

author

受著作權保護之影片的作者

content_title

受著作權保護之影片的名稱

matched_segments

包含下列鍵值組的物件陣列：* duration_in_seconds – 內容侵犯著作權的秒數 * segment_type – AUDIO 或 VIDEO * start_time_in_seconds – 設為影片的開始時間

owner_copyright_policy

傳回的物件包括：

  • name – 著作權擁有者政策的名稱

  • actions – action 物件陣列，其中包含著作權擁有者政策定義的緩解措施。針對不同地點，可能包括不同的緩解措施。

    • action – 針對侵犯著作權的影片採取的緩解措施。針對不同的國家／地區可以採取不同的緩解措施。可以是下列其中一個值：
      • BLOCK – 針對 geos 陣列中列出的廣告受眾封鎖此影片
      • MUTE - 針對 geos 陣列中列出的廣告受眾將此影片靜音

id
公開

影音素材編號。

is_comment_enabled

表示啟用或停用留言。不含相簿子項。

is_shared_to_feed
公開

僅限 Reels。當設定為 true 時，代表連續短片可同時顯示在動態消息和 Reels 頁籤中。當 false 時，代表連續短片只能顯示在 Reels 頁籤中。

無論該值為何，都不會決定連續短片是否實際顯示在 Reels 頁籤中，因為該連續短片可能不符合資格需求或未被演算法所選擇。請參閱連續短片規格，瞭解資格條件。

like_count

影音素材的按讚次數，包括對留言的回覆次數。不含相簿子影音素材的按讚次數，也不含以影音素材製作之推廣貼文的按讚次數。


如果透過另一個端點或欄位擴充進行間接查詢，當影音素材擁有者已隱藏按讚數時，則會忽略 like_count 欄位。

media_product_type
公開

發佈影音素材的介面。可以是 AD、FEED、STORY 或 REELS。僅開放 Instagram 圖形 API 使用。

media_type
公開

影音素材類型。可以是 CAROUSEL_ALBUM、IMAGE 或 VIDEO。

media_url
公開

影音素材的網址。

如果影音素材包含享有著作權保障的素材，或者是標註違反著作權的標示，回應中會忽略 media_url 欄位。享有著作權保障的素材包括連續短片的音訊。

owner
公開

建立影音素材的 Instagram 用戶編號。只有進行查詢的應用程式用戶也已建立影音素材時才會傳回，否則會傳回 username 欄位。

permalink
公開

影音素材的永久網址。

shortcode
公開

影音素材的簡碼。

thumbnail_url
公開

影音素材縮圖網址。只適用於 VIDEO 影音素材。

timestamp
公開

ISO 8601 格式的 UTC 建立日期（預設為 UTC ±00:00）。

username
公開

建立影音素材之用戶的用戶名稱。

關係連線

可透過欄位擴充傳回公開關係連線。

關係連線說明

children
公開。

代表相簿 IG 影音素材上 IG 影音素材物件的集合。

collaborators

代表 IG 影音素材物件上新增為協作者的用戶清單。僅開放 Instagram 圖形 API 使用。

comments

代表 IG 影音素材物件上 IG 留言的集合。

insights

代表 IG 影音素材物件上的社群互動衡量指標。僅開放 Instagram 圖形 API 使用。

cURL 範例

要求範例

curl -X GET \
  'https://graph.instagram.com/v21.0/17895695668004550?fields=id,media_type,media_url,owner,timestamp&access_token=IGQVJ...'

回應範例

{
  "id": "17918920912340654",
  "media_type": "IMAGE",
  "media_url": "https://sconten...",
  "owner": {
    "id": "17841405309211844"
  },
  "timestamp": "2019-09-26T22:36:43+0000"
}

更新

POST /<IG_MEDIA_ID>

啟用或停用對 IG 影音素材的留言功能。

限制

不支援直播影片 IG 影音素材。

Requirements

Instagram API with Instagram LoginInstagram API with Facebook Login

Access Tokens

  • Instagram User access token

Host URL

graph.instagram.com

graph.facebook.com

Login Type

Business Login for Instagram

Facebook Login for Business

Permissions
  • instagram_business_basic
  • instagram_business_manage_comments
  • instagram_basic
  • instagram_manage_comments
  • pages_read_engagement
  • pages_show_list

If the app user was granted a role via the Business Manager on the Page connected to the targeted IG User, you will also need one of:

  • ads_management
  • business_management

要求語法

POST https://graph.facebook.com/<API_VERSION>/<IG_MEDIA_ID>
  ?comment_enabled=<BOOL>
  &access_token=<ACCESS_TOKEN>

路徑參數

預留位置值

<API_VERSION>

API 版本。

<IG_MEDIA_ID>

必要項目。IG 影音素材編號。

查詢字串參數

索引鍵預留位置值

access_token

<ACCESS_TOKEN>

必要項目。應用程式用戶的用戶存取權杖。

comment_enabled

<BOOL>

必要項目。設定為 true 會啟用留言功能，設定為 false 則會停用留言功能。

cURL 範例

要求範例

curl -i -X POST \
 "https://graph.instagram.com/v21.0/17918920912340654?comment_enabled=true&access_token=EAAOc..."

回應範例

{
  "success": true
}

刪除

不支援執行此作業。