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.
To make it more convenient for developers, Meta has published the full set of Graph API calls for Facebook Reels on the Postman API Platform. For more information, see Postman Collections for Facebook Reels and Instagram Reels.
Property | Recommended | Min | Max |
---|---|---|---|
File Type | .mp4 | — | — |
Aspect Ratio | 9 x 16 | 9 x 16 | 9 x 16 |
Resolution | 1080 x 1920 pixels | 540 x 960 pixels | — |
Frame Rate | 24-60 frames per second | 24 frames per second | — |
Duration | — | 3 seconds | 90 seconds |
Video Settings |
| — | — |
Audio Settings |
| — | — |
When uploading a Reel, the user should be presented with disclosure of and options for control over how their Reels are used on Facebook.
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
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.
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.
The process for publishing Reels involves Resumable (non-chunking) protocol including endpoints
/{page-id}/video_reels?upload_phase=start
rupload.facebook.com/video-upload/{api-version}/{video-id}
/{video-id}?fields=status
/{page-id}/video_reels?upload_phase=finish
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
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.
curl -X POST \ "https://graph.facebook.com/v13.0/{page-id}/video_reels" \ -F "upload_phase=start" \ -F "access_token=EAADI..."
{ "video_id": "{video-id}", "upload_url": "https://rupload.facebook.com/video-upload/v13.0/{video-id}", }
There are two supported sources for uploaded videos, "Local File" and "Hosted File".
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}
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"
{"success": true}
Header | Description |
---|---|
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. |
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}
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}
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"
{"success": true}
Header | Description |
---|---|
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. |
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
curl -G "https://graph.facebook.com/v13.0/{video-id}" \ -H "Authorization: OAuth EAADI..." -d "fields=status"
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. |
{ "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) } } }
{ "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", } } }
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 | ||
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
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!'
The response will be a JSON object that indicates whether the request was successful.
{"success": true}
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
curl -X GET \ "https://graph.facebook.com/v13.0/{page-id}/video_reels" \ -F 'access_token=EAADI...'
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}" }