Publishing

The Video API allows you to publish Videos on Pages and Groups. Publishing on Users is not supported.

You can also publish Reels on Pages. For more information see Reels Publishing API.

The process for publishing Videos involves choosing an upload protocol and sending a POST request to the targeted Page or Group's /videos edge. The API suppports both Resumable and Non-Resumable upload protocols. We recommend that you use the Resumable Upload protocol as it is more versatile and can gracefully handle connection interruptions.

Note that all of the examples in this document use a Page node but apply equally to Group nodes.

Requirements

All publishing actions require an appropriate Access Token and Permissions based on the node you are targeting. While you are testing you can easily generate Tokens and grant your app Permissions by using the Graph API Explorer. Refer to our Get Started guide to see how to do this. When you are app is ready for production, you will likely have to implement Facebook Login to get Tokens and Permissions from your app users.

Publishing on Pages

The app user must be an Admin of the Page you are targeting. You will need the app user's Page Access Token and they must grant your app the pages_show_list, pages_read_engagement, and pages_manage_posts permissions.

Publishing on Groups

The app user must be an Admin of the Group you are targeting. You will need the app user's User Access Token and they must grant your app the publish_to_groups permission.

Resumable Upload

The Resumable Upload protocol is the preferred publishing protocol because you can split large videos into smaller chunks to avoid timeouts. This is especially useful for large videos where you are more likely to encounter a connection error. If you encounter a connection error while uploading a large video, you normally would have to reupload the entire video. But by using the Resumable Upload protocol you only have to reupload the affected chunk; chunks that have alread been uploaded do not need to be reuploaded.

You can publish a video on a Page or Group. Publishing involves the following steps:

1. Initialize an upload session on the Page or Group,
2. upload individual chunks in the order in which they should be assembled, and
3. end the upload session.

Once you end the upload session, we will reassemble the video, encode it, and publish it.

Limitations

Videos are limited to 10GB and 4 hours.

Step 1: Initialize An Upload Session

To initialize a video upload session, send a POST request to the Page Videos endpoint:

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

Include the following parameters:

Sample Request

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

Sample Response

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

Capture the start_offset and upload_session_id values returned by the API. You will use them in the next step to upload your first video chunk. You may also want to capture the video_id value. You don't need it for publishing, but it will be the eventual published video's ID.

Step 2: Upload Chunks Individually

Upload each of your video's chunks in the order in which they should be assembled by sending consecutive POST requests to the Page Videos endpoint:

POST /v18.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}

Include the following data as multipart/form-data in the body of the request:

Each time you successfully upload a chunk a new start_offset value will be returned. Repeat this request using the newly returned start_offset value and the name of the next video chunk to be uploaded (assigned to video_file_chunk) and gradually work your way through all of your remaining video chunks.

Sample Request for First Chunk

curl -X POST \
  "https://graph-video.facebook.com/v18.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"

Sample Response

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

Sample Request for Second Chunk

curl -X POST \
  "https://graph-video.facebook.com/v18.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"

Sample Response

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

Once you've uploaded your final chunk, the API should respond with matching start_offset and end_offset values, indicating that you can end the upload session.

Sample Final Response

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

Step 3: End The Upload Session

When you end the upload session we will reassemble the complete video, encode it, then publish it on the Page. To end the upload session, send one final POST request to the Page Videos endpoint:

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

Include the following parameters:

You can also include any additional parameters that the Page Videos endpoint supports, such as a title, description, and thumb.

Sample Request

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

Sample JSON Response

{
  "success":true
}

When you receive this response it indicates that we have begun assembling and encoding the complete video. You should be able to see published video within a minutes.

Non-Resumable Upload

We recommend that you upload files using the Resumable Upload protocol because it handles connection interruptions more efficiently and supports larger files. However, if you prefer to upload files using the Non-Resumable Upload protocol, you can do so by sending a POST request to the Page Videos edge and including either the source parameter (for local video files) or file_url parameter (for files hosted on a public server) in your request body as multipart/form-data. You can also include any additional parameters that the Page Videos endpoint supports, such as a title, description, and thumb.

Limitations

Videos are limited to 1GB and 20 minutes. If your video file is larger, split it into chunks and publish it using the Resumable Upload protocol instead.

Sample Local File Request

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

Sample Hosted File Request

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

Upon success, the API will respond with the ID of the published Video.

Sample Response

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

Video Thumbnails

We automatically generate thumbnail images using stills from published videos. Generated thumbnails may be enhanced to improve brightness, color, and contrast. You can provide your own thumbnail image by including the thumb field with either the Resumable or Non-Resumable protocol. If using the Resumable protocol, include the thumb field during Step 3: End The Upload Session. Thumbnail images that you provide will not be altered.

Thumbnail Image Requirements

Format: BMP, GIF, JPEG, PNG,TIFF
File Size: 10MB or less.

There are no image dimension requirements, but it should share the same aspect ratio as your video.

Sample Resumable Upload Request With Thumnbail

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

Sample JSON Response

{
  "success":true
}

Sample Non-Resumable Upload Request With Thumnbail

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

Sample Response

{
  "id":"287788272232962"
}