IG 用戶影音素材

代表 IG 用戶的 IG 影音內容物件集合。

從 2023 年 11 月 9 日開始，不再支援 media_type 的 VIDEO 值。請使用 REELS 影音素材類型將影片發佈到您的動態消息。

建立

POST /{ig-user-id}/media

建立能在貼文發佈流程中使用的圖像、輪播廣告、限時動態或連續短片 IG 容器。如需完整的發佈步驟，請參閱內容發佈指南。

限制

一般限制

容器將在 24 小時後失效。
如果連線至目標 Instagram 專業帳號的粉絲專頁需要粉絲專頁發佈授權（PPA），則必須完成 PPA，否則要求將失敗。
如果連線至目標 Instagram 專業帳號的粉絲專頁需要雙重驗證，Facebook 用戶也必須執行雙重驗證，否則要求將失敗。
不支援發佈至 Instagram TV。

Reels 限制

Reels 無法顯示在相簿輪播廣告中。
發佈時會尊重帳號隱私設定。例如，如果啟用了允許混搭，則所發佈的連續短片在發佈時會啟用混搭，但可以透過 Instagram 應用程式，在所發佈的連續短片上手動停用混搭。
音樂標籤僅適用於原始音訊。

限時動態的限制

限時動態會在 24 小時後失效。
支援影片網址或連續短片網址其中之一。
不支援發佈貼圖（例如連結、投票、地點）。

必備條件

類型	說明
存取權杖	用戶
企業管理平台角色	如果要建立用於商品標籤的容器，應用程式用戶在擁有 IG 用戶之 Instagram 商店的企業管理平台上，必須具有管理員角色。
Instagram 商店	如果要建立用於商品標籤的容器，IG 用戶必須要有申請獲准的 Instagram 商店，以及包含商品的商品目錄。
權限	`instagram_basic` `instagram_content_publish` `pages_read_engagement` 或 `pages_show_list` 如果應用程式用戶是透過企業管理平台獲得粉絲專頁角色，您還需要下列其中一項： `ads_management` `business_management` 如果要建立用於商品標籤的容器，您還需要： `catalog_management` `instagram_shopping_tag_products`
任務	所屬權杖用於要求中的應用程式用戶必須能夠在連線至目標 Instagram 帳號的粉絲專頁上執行 `MANAGE` 或 `CREATE_CONTENT` 任務。

圖像規格

格式：JPEG
檔案大小：最大 8MB。
長寬比：必須介於 4:5 至 1.91:1 範圍內
寬度下限：320（必要時將放大到下限）
寬度上限：1440（必要時將縮小到上限）
高度：視寬度和長寬比而異
色彩空間：sRGB。使用其他色彩空間的影像會將其色彩空間轉換為 sRGB。

連續短片規格

下列為 Reels 的規格：

容器：MOV 或 MP4（MPEG-4 Part 14），無編輯清單、檔案開頭 moov atom。
音訊轉碼器：AAC，最高 48khz 取樣速率，1 或 2 聲道（單聲道或立體聲）。
影片轉碼器：HEVC 或 H264，逐行掃描，封閉式 GOP，4:2:0 色彩採樣。
影格速率：23-60 FPS。
圖片大小：
- 最大欄（水平像素）：1920
- 所需的長寬比為 0.01:1 與 10:1 之間，但建議使用 9:16，以避免裁切或空白。
影片位元速率：VBR，最高 25Mbps
音訊位元速率：128kbps
時間長度：最長 15 分鐘，最短 3 秒
檔案大小：最大 1GB

下列為 Reels 封面相片的規格：

格式：JPEG
檔案大小：最大 8MB
色彩空間：sRGB。使用其他色彩空間的影像會轉換為 sRGB。
長寬比：建議使用 9:16，以避免裁切或空白。如果原始圖像的長寬比不是 9:16，我們會裁切圖像並使用最中間的 9:16 矩形做為連續短片的封面相片。如果您將連續短片分享至限時動態，我們會裁切圖像並使用最中間的 1:1 正方形做為動態消息貼文的封面相片。

限時動態圖像規格

格式：JPEG
檔案大小：最大 8 MB。
長寬比：建議使用 9:16，以避免裁切或空白
色彩空間：sRGB。使用其他色彩空間的影像會將其色彩空間轉換為 sRGB

限時動態影片規格

容器：MOV 或 MP4（MPEG-4 Part 14），無編輯清單、檔案開頭 moov atom。
音訊轉碼器：AAC，最高 48khz 取樣速率，1 或 2 聲道（單聲道或立體聲）。
影片轉碼器：HEVC 或 H264，逐行掃描，封閉式 GOP，4:2:0 色彩採樣。
影格速率：23-60 FPS。
圖片大小：
- 最大欄（水平像素）：1920
- 所需的長寬比為 0.1:1 與 10:1 之間，但建議使用 9:16，以避免裁切或空白
影片位元速率：VBR，最高 25Mbps
音訊位元速率：128kbps
時間長度：最長 60 秒，最短 3 秒
檔案大小：最大 100MB

要求語法

圖像容器

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
  ?image_url={image-url}
  &is_carousel_item={is-carousel-item}
  &caption={caption}
  &location_id={location-id}
  &user_tags={user-tags}
  &product_tags={product-tags}
  &access_token={access-token}

連續短片容器

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
?media_type=REELS
&video_url={reel-url}
&caption={caption}
&share_to_feed={share-to-feed}
&collaborators={collaborator-usernames}
&cover_url={cover-url}
&audio_name={audio-name}
&user_tags={user-tags}
&location_id={location-id}
&thumb_offset={thumb-offset}
&share_to_feed={share-to-feed}
&access_token={access-token}

輪播廣告容器

僅限輪播廣告容器。若要建立輪播廣告項目容器，請改為建立圖像或影片容器（不支援連續短片）。如需完整的發佈步驟，請參閱輪播廣告貼文。

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
?media_type=CAROUSEL
&caption={caption}
&share_to_feed={share-to-feed}
&collaborators={collaborator-usernames}
&location_id={location-id}
&product_tags={product-tags}
&children={children}
&access_token={access-token}

圖像限時動態容器

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
  ?image_url={image-url}
  &media_type=STORIES
  &access_token={access-token}

影片限時動態容器

POST https://graph.facebook.com/{api-version}/{ig-user-id}/media
  ?video_url={video-url}
  &media_type=STORIES
  &access_token={access-token}

路徑參數

預留位置	值
`{api-version}`	API 版本。
`{ig-user-id}` 必要項目	應用程式用戶的應用程式範圍用戶編號。

查詢字串參數

索引鍵	預留位置	說明
`access_token`	`{access-token}`	必要項目。應用程式用戶的用戶存取權杖。
`audio_name`	`{audio-name}`	僅限 Reels。Reels 影音素材的音訊名稱。無論是在建立連續短片時或後續從音訊頁面操作，您都只能重新命名一次。
`caption`	`{caption}`	圖像、影片或輪播廣告的說明文字。可以包括主題標籤（例如：`#crazywildebeest`）和 Instagram 用戶的用戶名稱（例如：`@natgeo`）。@ 提及的 Instagram 用戶會在發佈容器時收到通知。上限為 2,200 個字元、30 個主題標籤和 20 個 @ 標籤。不支援輪播廣告中的圖像或影片。
`collaborators`	`{caption}`	僅適用於動態消息圖像、Reels 和輪播廣告。最多 3 個 Instagram 用戶名稱作為 IG 影音素材的協作者清單。不支援限時動態。
`children`	`{children}`	輪播廣告的必要項目。僅適用輪播廣告。應顯示在已發佈輪播廣告中之每個圖像和影片的最多 10 個容器編號的陣列。輪播廣告最多可以包含 10 個圖像、影片或兩者的組合。
`cover_url`	`{cover-url}`	僅限 Reels。要做為 Reels 頁籤封面圖像的圖像路徑。我們將使用您指定的網址為圖像建立 cURL，因此圖像必須位在公開伺服器上。如果您同時指定 `cover_url` 和 `thumb_offset`，我們將使用 `cover_url` 並忽略 `thumb_offset`。圖像必須符合 Reels 封面相片的規格。
`image_url`	`{image-url}`	僅限圖像且為圖像的必要項目。圖像的路徑。我們將使用您指定的網址為圖像建立 cURL，因此圖像必須位在公開伺服器上。
`is_carousel_item`	`{is-carousel-item}`	僅適用圖像和影片。設定為 `true`。表示圖像或影片顯示在輪播廣告中。
`location_id`	`{location-id}`	與您想標註圖像或影片的位置關聯的粉絲專頁的編號。使用粉絲專頁搜尋 API 來搜尋名稱與搜尋字串相符的粉絲專頁，然後剖析結果，以識別已經為實體地點建立的任何粉絲專頁。請在查詢中包含 `location` 欄位，並驗證您想要使用的粉絲專頁具有地點資料。若嘗試使用不具地點資料的粉絲專頁建立容器，將會發生例外狀況代碼 `INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID` 的失敗。不支援輪播廣告中的圖像或影片。
`media_type`	`{media-type}`	輪播廣告、限時動態和連續短片的必要項目。表示容器適用於輪播廣告、限時動態或連續短片。可能的值如下： `CAROUSEL` `REELS` `STORIES`
`product_tags`	`{product-tags}`	商品標籤的必要項目。僅適用圖像和影片。指定要用來標註圖像或影片的產品標籤的物件陣列（最多 5 個；標籤和產品編號必須不重複）。每個物件應包含以下資訊： `product_id` - 必要項目。產品編號。 `x` - 僅限圖像。表示與已發佈影音素材圖像左邊緣的百分比距離的選用浮點數。數值必須在 `0.0` 至 `1.0` 範圍內。 `y` - 僅限圖像。表示與已發佈影音素材圖像上邊緣的百分比距離的選用浮點數。數值必須在 `0.0` 至 `1.0` 範圍內。例如： `[{product_id:'3231775643511089',x: 0.5,y: 0.8}]`
`share_to_feed`	`{share-to-feed}`	僅限 Reels。當設定為 `true` 時，代表連續短片可同時顯示在動態消息和 Reels 頁籤中。當設定為 `false` 時，代表連續短片只能顯示在 Reels 頁籤中。無論該值為何，都不會決定連續短片是否實際顯示在 Reels 頁籤中，因為該連續短片可能不符合資格需求或未被演算法所選擇。請參閱連續短片規格，瞭解資格條件。
`thumb_offset`	`{thumb-offset}`	適用於影片和連續短片。要做為封面縮圖圖像的影片或連續短片影格位置，單位為毫秒。預設值為 `0`，亦即影片或連續短片的第一個影格。針對連續短片，如果您同時指定 `cover_url` 和 `thumb_offset`，我們將使用 `cover_url` 並忽略 `thumb_offset`。
`user_tags`	`{user-tags}`	用戶標籤的必要項目。適用圖像和影片。公開用戶名稱和您想在圖像中標註的任何公開 Instagram 用戶的 `x`／`y` 座標的陣列。每個物件應包含以下資訊： `usernames` - 必要項目。公開用戶名稱。 `x` - 僅限圖像。表示與已發佈影音素材圖像左邊緣的百分比距離的選用浮點數。數值必須在 `0.0` 至 `1.0` 範圍內。 `y` - 僅限圖像。表示與已發佈影音素材圖像上邊緣的百分比距離的選用浮點數。數值必須在 `0.0` 至 `1.0` 範圍內。
`video_url`	`{video-url}`	影片和連續短片的必要項目。僅適用影片和連續短片。影片的路徑。我們使用傳入網址為影片建立 cURL，因此影片必須位在公開伺服器上。

回應

JSON 格式的物件，其中包含可用於發佈容器的 IG 容器編號。

影片上傳是非同步的，因此收到容器編號並不保證上傳成功。若要驗證影片是否已上傳，請在 IG 容器上要求 status_code 欄位。如果其值為 FINISHED，表示影片已成功上傳。

{
  "id":"{ig-container-id}"
}

要求範例

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

回應範例

{
  "id": "17889455560051444"
}

讀取

GET /{ig-user-id}/media

取得 IG 用戶的所有 IG 影音素材。

限制

傳回最高 10K 最近建立的媒體。
不支援限時動態 IG 影音素材，請改用 GET /{ig-user-id}/stories 端點。

必備條件

類型說明

存取權杖

用戶

權限

instagram_basic
pages_read_engagement 或 pages_show_list

如果應用程式用戶是透過企業管理平台獲得粉絲專頁角色，您還需要下列其中一項：

ads_management
business_management

時間型分頁

此端點支援時間型分頁。包含 since 和 until 查詢字串參數並搭配 Unix 時間戳記或 strtotime 資料值，以定義時間範圍。

要求範例

GET graph.facebook.com/17841405822304914/media

回應範例

{
  "data": [
    {
      "id": "17895695668004550"
    },
    {
      "id": "17899305451014820"
    },
    {
      "id": "17896450804038745"
    },
    {
      "id": "17881042411086627"
    },
    {
      "id": "17869102915168123"
    }
  ]
}

更新

不支援執行此作業。

刪除

不支援執行此作業。