影片 API

發佈

影片 API 讓您可以在專頁和群組發佈影片，但不支援向用戶發佈。

您也可以在專頁發佈連續短片。詳情請參閱連續短片發佈 API。

影片發佈程序包含選擇上載協定，以及將 POST 要求傳送到目標專頁或群組的 /videos 關係連線。此 API 支援可恢復和不可恢復的上載協定。我們建議使用可恢復的上載協定，此協定更加靈活，可以妥善處理連線中斷情況。

請注意，本文件的範例使用專頁節點，但同樣適用於群組節點。

必要條件

所有發佈動作均需根據目標節點使用相應的存取憑證和權限。測試時，您可以透過使用 Graph API 測試工具輕鬆產生憑證，並向您的應用程式授予權限。請參閱我們的新手入門指南，了解如何操作。應用程式準備好正式發佈時，您可能需要執行 Facebook 登入，以便從應用程式用戶處獲取憑證和權限。

在專頁發佈

應用程式用戶必須是目標專頁的管理員。您將需要應用程式用戶的專頁存取憑證，而且他們必須向您的應用程式授予 pages_show_list、pages_read_engagement 和 pages_manage_posts 權限。

在群組發佈

應用程式用戶必須是目標群組的管理員。您將需要應用程式用戶的用戶存取憑證，而且他們必須向您的應用程式授予 publish_to_groups 權限。

可恢復的上載

可恢復的上載協定是首選發佈協定，因為您可以將較大的影片分割為較小的區塊，以避免逾時。這尤其適用於上載較大的影片，此過程中更有可能遇到連線錯誤。如果上載較大影片時遇到連線錯誤，通常需要重新上載整段影片。不過，如果使用可恢復的上載協定，您便只需要重新上載受影響的區塊，無需重新上載已上載的區塊。

您可以在專頁或群組發佈影片。發佈程序包括以下步驟：

  1. 在專頁或群組初始化上載連線階段，
  2. 按區塊組合順序逐一上載區塊，然後
  3. 結束上載連線階段。

結束上載連線階段後，我們會重新組合影片、對其編碼，然後發佈該影片。

限制

影片大小上限為 10 GB，長度上限為 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。

限制

影片大小上限為 1 GB，長度上限為 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 欄位，以提供自己的縮圖。如果使用可恢復協定，請在第 3 步：結束上載連線階段中包含 thumb 欄位。您提供的縮圖將無法更改。

縮圖要求

格式：BMP、GIF、JPEG、PNG 或 TIFF
檔案大小：不超過 10 MB。

無圖像尺寸要求，但應該與影片保持相同的長闊比例。

帶縮圖的可恢復上載要求範例

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"
}