Reels Publishing API

This document explains how to publish a reel on a Page. For more information about Reels, see Reels Developer Documentation.

Facebook Reels Publishing API Sample is available on Github.

Publishing

Requirements

PropertyMin (or n/a)Max (or n/a)

Resolution

540 x 960 (540p)

n/a

Aspect Ratio

9x16

9x16

Frame Rate

23

n/a

Duration

4 sec

60 sec

File Size

n/a

n/a

Limitations

  • Publishing Reels on Groups or Users are not available.
  • Upload only supports the following formats for uploaded video/reels: 3g2, 3gp, 3gpp, asf, avi, dat, divx, dv, f4v, flv, m2ts, m4v, mkv, mod, mov, mp4, mpe, mpeg, mpeg4, mpg, mts, nsv, ogm, ogv, qt, tod, ts, vob, wmv.

Recommendations

  • File Type: MP4, MOV
  • Resolution: 1080x1920 or greater
  • Video Settings: H.264 compression, square pixels, fixed frame rate, progressive, AAC audio at 128kbps+

Sharing Disclosure

When uploading a Reel, the user should be presented with disclosure of and options for control over how their Reels are used on Facebook.

Privacy / Who can see this?

User selectable choice of audience. This selection corresponds to the privacy parameter in the publishing step. Posting to a Page has implicit public scope, and only the 'Public' option should be available. A mockup of how this disclosure could appear for posting to a Page is shown below. Sharing Disclosure Mockup

Permissions

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 your 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.

API Endpoints

The process for publishing Reels involves Resumable (non-chunking) protocol including endpoints

  • Initialize an upload session: /{page-id}/video_reels?upload_phase=start
  • Upload the video itself (rupload.facebook.com): rupload.facebook.com/video-upload/{api-version}/{video-id}
  • Status (Optional): /{video-id}?fields=status
  • Publish the video, and set metadata: /{page-id}/video_reels?upload_phase=finish

Step 1: Initialize Upload Session

To initialize a video upload session, send a POST request to the /video_reels Graph API endpoint on the corresponding page edge.

Host: graph.facebook.com

Endpoint: /{page-id}/video_reels

Response

When successful, the API response will include a “video_id” value which will be used in subsequent calls and the URLs of the endpoints for the Upload, Status and Publish steps.

Sample Request

curl -X POST \
  "https://graph.facebook.com/v13.0/{page-id}/video_reels" \
      -F "upload_phase=start" \
  -F "access_token=EAADI..."

Sample Response

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

Step 2: Upload the Video

There are two supported sources for uploaded videos, "Local File" and "Hosted File".

Local File Upload

This method can be used when the video file is available locally to the uploader.

To initiate the upload of the video asset, send a POST request using application/octet-stream as content type to the video-upload endpoint, including the video file in the request body.

Host: rupload.facebook.com

Endpoint: /video-upload/{api-version}/{video-id}

Sample Request

curl -X POST \
  "https://rupload.facebook.com/video-upload/v13.0/{video-id}" \
  -H "Authorization: OAuth EAADI..." \
  -H "offset: 0" \
  -H "file_size: 73400320" \
  --data-binary "@my_video_file.mp4"

Sample Response

{"success": true}

Headers

HeaderDescription

Authorization

Should contain “OAuth {access-token}”.

offset

The byte offset of the first byte being uploaded in this request.Generally should be set to 0, unless resuming an interrupted upload. If resuming an interrupted upload, set to the “offset” returned by /status.

file_size

The total size in bytes of the video being uploaded.

Resuming a Local File Upload (if interrupted)

If the video upload is interrupted, it can be resumed. This can be done by first retrieving the upload byte offset from the status endpoint, and then uploading the remaining bytes using the /video-upload/ endpoint.

The Offset header should be set to the offset/bytes_transferred value received from the status endpoint, or set to 0 to restart from the beginning of the upload. The file bytes sent in the subsequent request should start with the byte at “offset” (zero-based)

Host: rupload.facebook.com

Endpoint: /video-upload/{api-version}/{session-id}

Hosted File Upload

This method can be used when the video to upload is hosted on a public facing http/https server, such as a CDN.

Host: rupload.facebook.com

Endpoint: /video-upload/{api-version}/{video-id}

Sample Request

curl -X POST \
  "https://rupload.facebook.com/video-upload/v13.0/{video-id}" \
  -H "Authorization: OAuth EAADI..." \
  -H "file_url: https://some.cdn.url/video.mp4"

Sample Response

{"success": true}

Headers

HeaderDescription

Authorization

Should contain “OAuth {access-token}”.

file_url

The url for the publicly hosted video. Supported protocols are http and https. Other protocols, and urls requiring authentication are not currently supported.

Step 3: (Optional) Retrieve status of Upload session

You can retrieve the status of a publishing operation by sending a GET request for the status field on the video.

Host: graph.facebook.com

Endpoint: /{video-id}?fields=status

Sample Request

curl -G "https://graph.facebook.com/v13.0/{video-id}" \
  -H "Authorization: OAuth EAADI..."
  -d "fields=status" 

Sample Response

The response will be a JSON object that includes a status field. The status field will include the following nested fields:

Field Description

video_status

The overall status of the upload and processing.

uploading_phase

This structure contains information about progress through the uploading phase.The bytes_transferred field can be used in conjunction with the upload endpoint to resume an interrupted upload.

processing_phase

This structure contains information about progress through the processing phase.This phase encompasses generating alternate media encodings, thumbnails, and other assets necessary for publishing.

publishing_phase

This structure contains information about progress through the publishing phase. This phase encompasses adding the video to the page, and if scheduled, will describe when the video is intended to be published.

File successfully uploaded
{
  "status": {
    "video_status": "processing", // ready, processing, expired, error
    "uploading_phase": {
      "status": "in_progress", // not_started, in_progress, complete, error
      "bytes_transfered": 50002  // bytes received (also 'offset')
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "scheduled", // published, draft, scheduled
      "publish_time": 234523452 // actual or scheduled publish time (unix)
    }
  }
}
Example response with error structure in processing phase
{
  "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",
    }
  }
}

Step 4: Publish the Reel

When you end the upload session we will reassemble the complete video, encode it, then publish it on the selected page edge. To end the upload session and publish your video, send a POST request to the video_reels Graph API endpoint on the corresponding edge.

You can also include any of the additional parameters supported by Reels like description and title.

Field Required Comments

video_id

Yes

Values: {video-id} as returned from Initialize step.

upload_phase

Yes

Values: finish

video_state

Yes

Values: DRAFT, SCHEDULED, PUBLISHED

description

User supplied string.

title

User supplied string.

targeting

See reference

scheduled_publish_time

Unix timestamp integer for scheduled publish time.

If set, this time must be greater than 10 minutes from the current time, and must be coupled with setting video_state to 'SCHEDULED'.

Host: graph.facebook.com

Endpoint: /{page-id}/video_reels

Sample Request

curl -X POST \
  "https://graph.facebook.com/v13.0/{page-id}/video_reels" \
  -F 'access_token=EAADI...' \
  -F 'video_id={video-id}' \
  -F 'upload_phase=finish' \
  -F 'video_state=PUBLISHED' \
  -F 'description=What a great day. Watch until the end!'

Sample Response

The response will be a JSON object that indicates whether the request was successful.

{"success": true}

Step 5: (Optional) Retrieve the published Reels

You can access all Reels published to your page by sending a GET request to /{page-id}/video_reels.

Host: graph.facebook.com

Endpoint: /{page-id}/video_reels

Sample Request

curl -X GET \ 
  "https://graph.facebook.com/v13.0/{page-id}/video_reels" \
  -F 'access_token=EAADI...'

Sample Response

The response will be a JSON object that indicates whether the request was successful.

{
  "data": [
      {
        "updated_time": "{date}",
        "id": "{video-id}"
      },
      {
        "description": "sample_description",
        "updated_time": "{date}",
        "id": "{video-id}"
      },
      ...
    ],
    "paging": {
    "cursors": {
      "before": "{token}",
      "after": "{token}"
    },
    "next": "https://graph.facebook.com/v13.0/{page-id}/video_reels?access_token={access-token}"
}