Meta 的 Facebook 限時動態 API

本文件說明如何使用 Facebook 限時動態 API 在 Facebook 粉絲專頁上發佈限時動態。

若要發佈限時動態,您需要執行以下步驟:

  1. 將您的影音素材上傳到 Meta 伺服器
  2. 以限時動態將影音素材發佈到您的粉絲專頁

準備工作

本指南假設您已閱讀粉絲專頁 API 總覽及實作所需的元件,並已順利完成「開始使用」指南

  • 您需要實作「Facebook 登入」或「商家專用 Facebook 登入」,才能向您的應用程式用戶要求存取其 Facebook 粉絲專頁和接收粉絲專頁存取權杖所需的權限。

  • 您的應用程式用戶需要能夠在存取權杖中表示的粉絲專頁上執行 CREATE_CONTENT 任務,並為您的應用程式授予以下權限:

    • pages_manage_posts
    • pages_read_engagement
    • pages_show_list

如果您在 API 要求中使用企業系統用戶,也需要 business_management 權限。

影音素材需求

您必須提供符合以下規格的相片或影片。

相片規格

屬性規格

檔案類型

.jpeg、.bmp、.png、.gif、.tiff

檔案大小

檔案不能超過 4MB。對於 .png 檔案,建議不要超過 1MB,否則圖像可能會出現像素化。

影片規格

屬性規格

檔案類型

.mp4(建議)

長寬比

9 x 16

解析度

1080 x 1920 像素(建議)。最低為 540 x 960 像素

影格速率

每秒 24 至 60 影格

時間長度

3 至 90 秒。

以限時動態發佈在 Facebook 粉絲專頁上的連續短片不能超過 60 秒。

影片設定

  • 色度二次採樣 4:2:0
  • 封閉式 GOP(2-5 秒)
  • 壓縮格式 – H.264、H.265(亦支援 VP9、AV1)
  • 固定影格速率
  • 漸進式掃描

音訊設定

  • 音訊位元速率 – 128kbs+
  • 聲道 – 立體聲
  • 音訊轉碼器 – AAC 低複雜度
  • 採樣率 – 48kHz

限制

  • 為限時動態上傳的相片或影片不能已經用於先前發佈的貼文
  • 影片限時動態不能超過 60 秒
  • 若要在 GET 要求中包含已典藏的限時動態以查看限時動態清單,您必須開啟 Facebook 限時動態典藏功能

最佳作法

測試 API 呼叫時,可以將 access_token 參數組合包含在存取權杖中。不過,從應用程式進行安全呼叫時,請使用存取權杖類別

本文件中的程式碼範例採用方便閱讀的格式。請將粗體、斜體值(例如 page_id)換成您的值。

影片限時動態

若要在 Facebook 粉絲專頁上發佈影片限時動態,您需要與 Meta 伺服器初始化影片上傳連線階段、將影片上傳到 Meta 伺服器,然後發佈影片限時動態。

步驟 1:初始化連線階段

若要初始化上傳連線階段,請傳送 POST 要求至 /page_id/video_stories 端點(其中 page_id 為您的 Facebook 粉絲專頁編號),並將 upload_phase 參數設為 start

要求範例

curl -X POST "https://graph.facebook.com/v21.0/page_id/video_stories" \
      -d '{
           "upload_phase":"start",
         }'

成功後,您的應用程式會收到 JSON 回應,其中包含影片編號以及影片上傳的 Facebook 網址。

回應範例

{
  "video_id": "video_id",
  "upload_url": "https://rupload.facebook.com/video-upload/v21.0/video_id",
}  

步驟 2:上傳影片

您已經將上傳連線階段初始化並收到上傳網址,現在可以上傳影片了。您可以上傳:

上傳託管檔案

若要上傳託管檔案,請傳送 POST 要求至您在初始化步驟中收到的 upload_url 端點,並使用下列參數:

  • file_url 設為影片檔案的網址
要求範例
curl -X POST "https://rupload.facebook.com/video-upload/v21.0/video_id" \
	-H "file_url: https://some.cdn.url/video.mp4"

上傳本機檔案

若要上傳本機檔案,請傳送 POST 要求至您在初始化步驟中收到的 upload_url 端點,並使用下列參數:

  • offset 設為 0
  • file_size 設為所要上傳影片的總位元數大小
要求範例
curl -X POST "https://rupload.facebook.com/video-upload/v21.0/video_id" \
	-H "offset: 0" \
        -H "file_size: file_size_in_bytes" \
	--data-binary "@/path/to/file/my_video_file.mp4"

上傳成功後,您的應用程式會收到 success 設為 true 的 JSON 回應。

上傳回應範例
{
    "success": true
}  

上傳中斷

如果影片上傳中斷,您可以重新開始上傳或恢復上傳。

  • 若要重新開始上傳,請重新傳送 POST 要求,並將 offset 設為 0
  • 若要恢復上傳,請重新傳送 POST 要求,並將 offset 設為狀態檢查傳回的 bytes_transfered 值。

取得上傳狀態

若要在上傳或發佈期間檢查影片的狀態,請傳送 GET 要求至 /video_id 端點,並使用下列參數:

  • fields 設為 status
要求範例
curl -X GET "https://graph.facebook.com/v21.0/video_id" \
	-d "fields=status"

成功後,您的應用程式會收到 JSON 回應,其中包含:

  • status 物件,其中包含:
    • video_status,其值為 readyprocessingexpirederror
    • uploading_phase 物件,其中包含下列鍵值組:
      • status 設為 in_progressnot_startedcompleteerror
      • bytes_transfered 設為已上傳的位元數;如果上傳中斷,可用作 offset 的值。
    • processing_phase 物件,其中包含下列鍵值組:
      • status 設為 in_progressnot_startedcompleteerror
    • processing_phase 物件,其中包含下列鍵值組:
      • status 設為 in_progressnot_startedcompleteerror
      • publish_status 設為 publishednot_published
      • publish_time 設為實際或發佈時間的 UNIX 時間戳記
回應範例
以下回應表示檔案已成功上傳。
{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "in_progress", 
      "bytes_transfered": 50002 
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "published",
      "publish_time": 234523452 
    }
  }
}
以下回應表示處理階段發生錯誤。
{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "complete"
    },
    "processing_phase": {
      "status": "not_started",
      "error": {
        "message": "Resolution too low. Video must have a minimum resolution of 540p."
      }
    }
    "publishing_phase": {
      "status": "not_started"
    }
  }
}

步驟 3:發佈影片限時動態

若要發佈影片限時動態至您的粉絲專頁,請傳送 POST/page_id/video_stories 端點,並使用下列參數:

  • video_id 設為所上傳影片的編號
  • upload_phase 設為 finish

要求範例

curl -X POST "https://graph.facebook.com/v21.0/page_id/video_stories" \
      -d '{
           "video_id": "video_id",
           "upload_phase": "finish"
         }'

成功後,您的應用程式會收到包含下列鍵值組的 JSON 回應:

  • success 設為 true
  • post_id 設為限時動態貼文的編號

回應範例

{
  "success": true,
  "post_id": 1234
}

相片限時動態

步驟 1:上傳相片

請參閱粉絲專頁貼文參考資料 ,瞭解如何使用 /page_id/photos 端點上傳相片至 Meta 伺服器。請務必包含 published 參數,並將其設為 false

步驟 2:發佈相片限時動態

若要發佈相片限時動態至您的粉絲專頁,請傳送 POST/page_id/photo_stories 端點,並使用下列參數:

  • photo_id 設為所上傳相片的編號

要求範例

curl -X POST "https://graph.facebook.com/v21.0/page_id/photo_stories" \
      -d '{
           "photo_id": "photo_id"
         }'

成功後,您的應用程式會收到包含下列鍵值組的 JSON 回應:

  • success 設為 true
  • post_id 設為限時動態貼文的編號

回應範例

{
  "success": true,
  "post_id": 1234
}

取得限時動態

若要取得粉絲專頁的所有限時動態清單以及每個限時動態的相關資料,請傳送 GET 要求至 /page_id/stories 端點,其中 page_id 是您要查看之粉絲專頁的編號。

要求範例

    
curl -i -X GET "https://graph.facebook.com/v21.0/page_id/stories"

成功後,您的應用程式會收到包含物件陣列的 JSON 回應,其中各物件包含發佈在粉絲專頁上之各個限時動態的相關資訊。每個物件皆包含下列鍵值組:

  • post_id 設為所發佈之限時動態貼文的編號
  • status 設為 PUBLISHEDARCHIVED
  • creation_time 設為發佈限時動態的 UNIX 時間戳記
  • media_type 設為 videophoto
  • media_id 設為限時動態貼文中之影片或相片的編號
  • url 設為限時動態貼文的 Facebook 網址,例如 https://facebook.com/stories/8283482737484972

回應範例

{
  "data": [
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "video",
      "media_id": "video_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "ARCHIVED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    ...
  ],
}

您可以依照狀態、已發佈或已封存,以及日期(使用 sinceuntil 參數)來篩選限時動態。