影片 API

發佈

影片 API 可讓您在粉絲專頁和社團發佈影片。不支援在用戶發佈。

您也可以在粉絲專頁發佈 Reels。如需詳情，請參閱 Reels 發佈 API。

發佈影片的流程包含選擇上傳通訊協定及發送 POST 要求至目標的粉絲專頁或社團的 /videos 關係連線。API 同時支援可續傳和不可續傳的上傳通訊協定。建議使用可續傳的上傳通訊協定，因其擁有更多功能，可從容處理連線中斷的問題。

請注意，本文件中的例子使用粉絲專頁節點，但也能同樣套用到社團節點。

需求

所有發佈動作都需要視您的目標節點取得適當的存取權杖和權限。在測試時，您可使用圖形 API 測試工具輕鬆產生權杖，並授予應用程式權限。請參閱開始使用指南，以瞭解操作方式。當您的應用程式準備進入生產時，您可能需要實作 Facebook 登入，以取得應用程式用戶的權杖和權限。

在粉絲專頁發佈

應用程式用戶必須是目標的粉絲專頁管理員。您需要取得應用程式用戶的粉絲專頁存取權杖，且他們需要為您的應用程式授予 pages_show_list、pages_read_engagement 和 pages_manage_posts 權限。

在社團發佈

應用程式用戶必須是目標的社團管理員。您需要取得應用程式用戶的用戶存取權杖，且他們需要為您的應用程式授予 publish_to_groups 權限。

可續傳的上傳

可續傳的上傳通訊協定允許將大型影片分割為較小的區塊，以避免逾時，因此是偏好使用的發佈通訊協定。這對比較可能發生連線錯誤的大型影片特別有用。如果您在上傳大型影片時遇到連線錯誤，通常需要重新上傳整個影片。如果使用可續傳的上傳通訊協定，則只需要重新上傳受影響的區塊；不需要重新上傳已上傳的區塊。

您可在粉絲專頁或社團上發佈影片。發佈包含下列步驟：

  1. 在粉絲專頁或社團初始化上傳連線階段，
  2. 依照組合順序上傳個別區塊；然後
  3. 結束上傳連線階段。

結束上傳連線階段後，我們將組合影片、進行編碼，然後發佈影片。

限制

影片上限為 10GB 和 4 小時。

步驟 1：初始化上傳連線階段

若要初始化影片上傳連線階段，請發送 POST 要求至粉絲專頁影片端點：

POST /v19.0/{page-id}/videos
  ?upload_phase=start
  &access_token={access-token}
  &file_size={file-size}

包含下列參數：

參數名稱值

upload_phase

start

access_token

如果是在粉絲專頁發佈，為粉絲專頁存取權杖，如果是在社團發佈，則為用戶存取權杖。

file_size

影片檔案總大小（單位為位元組）。

要求範例

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "upload_phase=start" \
  -F "access_token=EAADI..." \
  -F "file_size=22420886"

回應範例

{
  "video_id":"2918040888250909",          //Capture this value (optional)
  "start_offset":"0",                     //Capture this value
  "end_offset":"1048576",
  "upload_session_id":"2918040901584241"  //Capture this value
}

擷取 API 傳回的 start_offset 和 upload_session_id 值。您將在後續步驟中使用這些值上傳第一個影片區塊。您也可以擷取 video_id 值。此數值非發佈時所需，但會是發佈影片的最終編號。

步驟 2：個別上傳區塊

發送連續的 POST 要求至粉絲專頁影片端點，依照組合順序上傳您的影片區塊：

POST /v19.0/{page-id}/videos
  ?upload_phase=transfer
  &access_token={access-token}
  &upload_session_id={upload-session-id}
  &start_offset={start-offset}
  &video_file_chunk={video-file-chunk}

將下列資料當成 multipart/form-data 加入要求內文：

表單資料名稱值

upload_phase

transfer

access_token

如果是在粉絲專頁發佈，為粉絲專頁存取權杖，如果是在社團發佈，則為用戶存取權杖。

upload_session_id

您的上傳連線階段編號。

start_offset

先前回應傳回的 start_offset 值。

video_file_chunk

所上傳影片區塊的名稱。

每次成功上傳區塊時，都會傳回一個新的 start_offset 值。使用新傳回的 start_offset 值和要上傳的下一個影片區塊的名稱（指派至 video_file_chunk）重複發送此要求，直到完成其餘所有的影片區塊。

第一個區塊的要求範例

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos"  \
  -F "upload_phase=transfer" \
  -F "upload_session_id=2918040901584241" \
  -F "access_token=EAADI..." \
  -F "start_offset=0" \
  -F "video_file_chunk=@/Users/...xaa"

回應範例

{
  "start_offset":"10485760",  //Value for second chunk
  "end_offset":"15728640"
}

第二個區塊的要求範例

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos"  \
  -F "upload_phase=transfer" \
  -F "upload_session_id=2918040901584241" \
  -F "access_token=EAADI..." \
  -F "start_offset=10485760" \
  -F "video_file_chunk=@/Users/...xab"

回應範例

{
  "start_offset":"20971520",  //Value for third chunk
  "end_offset":"22420886"
}

上傳完最後一個區塊後，API 應會傳回相符的 start_offset 和 end_offset 值，表示您可以結束上傳連線階段。

最終回應範例

{
  "start_offset":"22420886",  //When values match you can
  "end_offset":"22420886"     //end the upload session
}

步驟 3：結束上傳連線階段

結束上傳連線階段時，我們將組合完整影片、進行編碼，然後發佈到粉絲專頁上。若要結束上傳連線階段，請發送最後一個 POST 要求至粉絲專頁影片端點：

POST /v19.0/{page-id}/videos
  ?upload_phase=finish
  &access_token={access-token}
  &upload_session_id={upload-session-id}

包含下列參數：

參數名稱值

upload_phase

finish

access_token

如果是在粉絲專頁發佈，為粉絲專頁存取權杖，如果是在社團發佈，則為用戶存取權杖。

upload_session_id

您的上傳連線階段編號。

您也可加入粉絲專頁影片端點支援的任何其他參數，例如 title、description 和 thumb。

要求範例

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos"  \
  -F "upload_phase=finish" \
  -F "access_token=EAADI..." \
  -F "upload_session_id=2918040901584241"

JSON 回應範例

{
  "success":true
}

收到此回應時，表示我們已開始組合及編碼完整影片。您應該能在幾分鐘內查看發佈的影片。

不可續傳的上傳

可續傳的上傳通訊協定能讓您更有效處理連線中斷的問題，且支援較大的檔案，因此我們建議使用此通訊協定上傳檔案。不過，如果您偏好使用不可續傳的上傳通訊協定來上傳檔案，可透過發送 POST 要求至粉絲專頁影片關係連線並在要求內文中加入 source 參數（用於本機影片檔案）或 file_url 參數（用於公開伺服器上託管的檔案）作為 multipart/form-data 來上傳檔案。您也可加入粉絲專頁影片端點支援的任何其他參數，例如 title、description 和 thumb。

限制

影片上限為 1GB 和 20 分鐘。如果您的影片檔案較大，請將影片分割成區塊，然後改用可續傳的上傳通訊協定發佈。

本機檔案要求範例

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "access_token=EAADd..." \
  -F "source=@/Users/...incredible.mov"

託管檔案要求範例

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "access_token=EAADd..." \
  -F "file_url=https://socialsizz.../incredible.mov"

成功時，API 會以發佈的影片編號回應。

回應範例

{
  "id":"287788272232962"  //ID of the published Video
}

影片縮圖

我們會自動使用發佈影片的靜態影像來產生縮圖圖像。產生的縮圖可能會經過強化，以利改善其亮度、色彩與對比。您可以在可續傳或不可續傳的通訊協定中加入 thumb 欄位，以提供您自己的縮圖圖像。如果使用可續傳的通訊協定，請將 thumb 欄位加入到步驟 3：結束上傳連線階段。我們不會修改您提供的縮圖圖像。

縮圖圖像要求

格式：BMP、GIF、JPEG、PNG、TIFF
檔案大小：10MB 以下。

沒有圖像尺寸要求，但應使用與影片相同的長寬比。

含縮圖的可續傳上傳要求範例

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "upload_phase=finish" \
  -F "access_token=EAADI..." \
  -F "upload_session_id=2918040901584241"
  -F "thumb=@/Users/...thumbnail_image.png"

JSON 回應範例

{
  "success":true
}

含縮圖的不可續傳上傳要求範例

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "access_token=EAADd..." \
  -F "source=@/Users/...incredible.mov"
  -F "thumb=@/Users/...thumbnail_image.png"

回應範例

{
  "id":"287788272232962"
}