Uploading Videos with the Graph API

We support a resumable and non-resumable video upload protocols. This document provides details and examples of the resumable upload protocol and the non-resumable upload methods.

Supported Formats

The aspect ratio of the video must be between 9x16 and 16x9. We support the following formats for uploaded videos:

3g2, 3gp, 3gpp, asf, avi, dat, divx, dv, f4v, flv, gif, m2ts, m4v, mkv, mod, mov, mp4, mpe, mpeg, mpeg4, mpg, mts, nsv, ogm, ogv, qt, tod, ts, vob, and wmv.

Videos must be published to graph-video.facebook.com instead of the regular Graph API URL (graph.facebook.com).

Resumable Uploading

Upload videos as chunks, handle errors, and resume the upload of any remaining chunks. There are three different upload phases:

There are several advantages when you use resumable, chunked upload for your video:

  • Reliability – You can retry upload on specific chunks in case of data loss or connection issues.
  • File Size Limits - Resumable upload API helps you to limit the chunk size and avoid timeouts, so you can upload larger file sizes for videos.

Publish videos to the following endpoints:

For full list of parameters and actions that video support, see Graph API Video Reference docs.

Limitations

Resumable uploading supports videos that are up to 10GB and 4 hours long.

Starting the Upload Session

Start a resumable upload by initializing a session. To make a start request and create a video upload session, send a POST request to the /{object-id}/videos edge, where {object-id} is your {page-id}, {user_id}, {event_id}, or {group_id}, set the upload_phase field to start, and specify file_size, in bytes.

Sample Request

curl -X POST \
  "https://graph-video.facebook.com/{object-id}/videos"  \
  -F "access_token={your-access-token}" \
  -F "upload_phase=start" \
  -F "file_size=152043520"

Sample JSON Response

{
  "upload_session_id":"1564747013773438",    //ID of the upload session
  "video_id":"1564747010440105",             //ID of the uploading video 
  "start_offset":"0",                        //Start byte position of the first chunk to send. Will be 0.
  "end_offset":"52428800"                    //End byte position of the next file chunk to send
}

In the example above, the server wants you to upload [0, 52428800] part of your video. To do this, you would need to slice the file into chunks according to the start and end offsets, then send those chunks with transfer requests.

Uploading Video Chunks

Once you have chunks ready to upload with the right start_offset and end_offset you can make a transfer request to upload the chunk, and get the offset for the next chunk.

Split the video with the UNIX command split -b{X}m {filename}. This command splits your file into multiple parts of X MB each.

To upload the first video chunk, send a POST request to the /{object-id}/videos edge, where {object-id} is your {page-id}, {user_id}, {event_id}, or {group_id}, set the upload_phase field to transfer, set start_offset to 0, and video_file_chunk (multipart/form-data).

Sample Request of First Chunk

curl -X POST \
  "https://graph-video.facebook.com/{object-id}/videos"  \
  -F "access_token={your-access-token}" \
  -F "upload_phase=transfer" \
  -F “start_offset=0" \                                //Start byte position of this chunk, which is `0`.
  -F "upload_session_id={your-upload-sesson-id}" \     //The session id returned in the `start` phase.
  -F "video_file_chunk=@chunk1.mp4"                    //The video chunk, encoded as form data.

Sample JSON Response

{
  "start_offset":"52428800",    //Start byte position of the next file chunk.
  "end_offset":"104857601"      //End byte position of the next file chunk.
}

The response indicates the start and endpoints for the next chunk.

Now you should cut and upload the second chunk with range [52428800, 104857601] from your file.

Sample Request of Second Chunk

curl -X POST \
  "https://graph-video.facebook.com/{object-id}/videos"  \
  -F "access_token={your-access-token}" \
  -F "upload_phase=transfer" \
  -F "start_offset=52428801" \
  -F "upload_session_id={your-upload-sesson-id}" \
  -F "video_file_chunk=@chunk2.mp4"

Sample JSON Response

{
  "start_offset":"104857601",
  "end_offset":"152043520"
}

Again, the response indicates the start and endpoints for the next chunk.

Now you should cut and upload the third chunk with range [104857601, 152043520] from your file.

Sample Request of Third Chunk

curl -X POST \
  "https://graph-video.facebook.com/{object-id}/videos"  \
  -F "access_token={your-access-token}" \
  -F "upload_phase=transfer" \
  -F "start_offset=104857601" \
  -F "upload_session_id={your-upload-session-id}" \
  -F "video_file_chunk=@chunk3.mp4"

Sample JSON Response

{
  "start_offset":"152043520",
  "end_offset":"152043520"
}

At this point, the server response shows start_offset equal to end_offset. This means you uploaded the whole file and you have nothing more for that file to upload. As a final step, you need to post this video and close the upload session.

At any time during an upload if you get any errors you can retry uploading that chunk. Typically errors are due to response issues. Retry your upload at the chunk when the error occurred. For more information about errors, see:

Publishing the Video

The publish_actions permission has been deprecated. If your app has already been approved for this permission, you can continue using it to publish videos until August 1, 2018. To publish videos to User timelines, Groups, or Pages after that date, please use the Sharing Dialog.

Once you upload all chunks, make a finish request to complete the upload, post the video, and queue it for asynchronous encoding.

Make a POST request with the parameter upload_phase(enum):finish to the /{page-id, /{user-id}, /{event-id}, or /{group-id}/videos edge.

The request parameters are:

  • Post Metadata and All Available Fields: In the request you can add all the metadata of the post and send all available fields documented in /{page_id, /{user_id}, /{event_id}, /{group_id}/videos edges. See Page Videos, User Videos and Event Videos References.
  • upload_phase (enum) - Set to finish.
  • upload_session_id (int32) - The session id returned by the start phase.

The server response includes:

  • success (bool) - Whether the video was uploaded successfully

Following our example above:

curl -X POST \
  "https://graph-video.facebook.com/{your-object-id}/videos"  \
  -F "access_token={your-access-token}" \
  -F "upload_phase=finish" \
  -F "upload_session_id={your-upload-session-id}" 

Sample JSON Response

{"success":true}

After this request successfully completes your uploading is complete. You will see the video soon after the encoding is done.

Resumable Uploading Errors

Initialize an Upload Session, start phase:

Error SubcodeError TypeDescriptionRecommendations

6000

GraphException

There was a problem uploading your video file. Please try again with another file.

Retry several times and report bug if this still doesn't work.

1363042

CodedException

No Permission to Upload Video: You don't have permission to upload a video here.

Get valid access token. See Access Tokens

1363023

CodedException

The video you tried to upload is too large. The maximum size for a video is 2 GB. Please try again with a smaller file.

Upload with small file or talk to Facebook for capacity

1363022

CodedException

The video you tried to upload is too small. The minimum size for a video is 1 KB. Please try again with a larger file.

Make sure your file is not empty.

Upload chunks, transfer phase:

Error CodeError MessageRecommendations

1363030

Video Upload Timeout. Your video upload timed out before it could be completed. This is probably because of a slow network connection or because the video is too large. Please try again.

Fix issues then retry upload.

1363019

There was a problem uploading your video. Please try uploading it again.

Retry upload.

1363037

There was a problem uploading your video. Please try uploading it again. error_data:{start_offset:0,end_offset:392695}

Returned when the server receives an invalid start offset from the client. Try to parse the start_offset and end_offset from error message and do a retry again.

1363033

There was a problem uploading your video. Please try uploading it again.

Typically caused by connection issue, which causes server to receive partial file. Need to retry.

1363020

No Video Selected. Please select the video you want to upload.

Need to include a file name in the parameter

1363005

No Permission to Edit Video. You lack permission to edit this video.

Need to include a file name in the parameter

1363031

No Video Detected. It looks like you are uploading a file that is not a video. Please try uploading a supported format. See Graph API Reference, Supported Formats

Provide supported format

1363045

There was a problem uploading your video. Please try uploading it again.

The upload video does not match the size. For example, someone start an upload session to upload 1MB file, but uploads more than 1MB data.

1363032

No Video Detected. It looks like you are uploading a file that is not a video. Please try uploading a supported format. See Graph API Reference, Supported Formats

Provide supported format

1363025

Video Too Short: The video you tried to upload is too short. The minimum length for a video is 1 second. Please upload a longer video.

Provide video of minimum duration

1363026

Video Too Long. The video you tried to upload is too long. The maximum length for a video is 40 minutes. Please upload a shorter video.

Provide video under maximum duration

1363021

Video Upload Problem: There was a problem uploading your video. Please try again.

Retry upload

1363041

Error Uploading Video: There was a problem uploading your video. Please try uploading it again.

Retry upload

1363022

Video Too Small: The video you tried to upload is too small. The minimum size for a video is 1 KB. Please try again with a larger file.

Provide minimum sized video

1363023

Video Too Large: The video you tried to upload is too large. The maximum size for a video is 2 GB. Please try again with a smaller file.

Provide video less than maximum allowed size.

1363024

Unsupported Video Format: The video you try to upload is in a format that is not supported. Please try again with a video in a supported format, see Graph API Reference, Supported Formats.

Provide supported format.

Post a video:

Error CodeError MessageRecommendation

1617005

Cannot Add Tag: You do not have permission to add this tag.

See Permissions with Facebook Login.

1617003

Too Many User Tags: Sorry, we can not save your tag because this video has already been tagged with the maximum number of people allowed. Please see the FAQ page on Tagging.

Limit allowed tags.

1363011

Error Storing or Editing Video: There was an error storing or editing your video. Please try again.

Retry post.

1617006

Already Tagged: The specified user or page is already tagged in this video.

1357005

User-provided request parameters do not match the types specified in param_get/param_post.

1607004

The date provided is earlier than the one for User birthday.

Check and verify the date is correct then retry the post

1363041

Error Uploading Video: There was a problem uploading your video. Please try uploading it again.

Check that you do not use an expired upload session id.

1607002

Invalid Date, TIMELINE__INVALID_TIME_TOO_EARLY. You cannot post to that time period.

Change to a later date.

Non-Resumable Uploading

In addition to resumable uploading, you can also upload complete videos files with one of these methods:

  • Sending multi-part HTTP request with the video source.
  • Providing a URL for a downloadable video via the file_url parameter. Available as of v2.3. The video should be downloaded within 5 minutes.

Limitations - Non-Resumable upload supports video uploads that are up to 1GB and 20 minutes long.

Video Notifications

Subscribe to real-time updates to a callback url when video processing is done, and your video's ready to be used. Notification are not sent for videos that are uploaded as secret or no_story.

Using the real-time updates subscriptions, subscribe to the Page or User where you uploaded the video.

The /video/status field displays the value of ready, processing, or ERROR.

Publishing Videos with Thumbnails

Videos must be encoded as multipart/form-data and published to graph-video.facebook.com instead of graph.facebook.com.

POST /{page-id}/videos HTTP/1.1
Host: graph-video.facebook.com

source=%7Bvideo-data%7D&thumb=%7Bimage-data%7D

Restrictions

A thumbnail image from the main video content is required. This image should highlight key moments or scenes from the video. Do not show start or end tags, logos or other stills that are not part of the main video content.

Crossposting Videos

Creating Crossposted Videos

Create video posts from existing post without the need to re-upload the video again. Major benefit of this is that you can see total video insights from all crossposts and a breakdown of metrics across the multiple posts created from the video.

The parameter crossposted_video_id is required to specify the video from which the new post is created. To determine whether your video can be used for creating crossposts, query the is_crossposting_eligible field. You can also use videos from other Pages in your Business Manager to create crossposts if you have permission.

To create a new post from an existing video, send a POST request to the /{object-id}/videos edge, where {object-id} is your {page-id}, {user_id}, {event_id}, or {group_id}, and set the crossposted_video_id field to the {video-id} of the video you want to crosspost. Do not set the upload_phase field in this request.

Sample Request

curl \
-X POST \
"https://graph-video.facebook.com/{object-id}/videos"  \
-F "access_token={your-access-token}" \
-F "crossposted_video_id={your-video-id}"

Sample JSON Response

 {"id":"{your-crossposted-video-id}"}   // A new video ID is created.
      

Allowing Pages in Business Manager to Crosspost Videos

Allow other pages managed by the same Business Manager to crosspost your existing video using allow_bm_crossposting field.

To enable crossposting permissions on an existing video, send a POST request to the /{object-id} node, where {object-id} is your {page-id}, {user_id}, {event_id}, or {group_id}, and set the allow_bm_crossposting field to 1.

Sample Request

curl -X POST \
 "https://graph-video.facebook.com/{object-id}"  \
 -F "access_token={your-access-token}" \
 -F "allow_bm_crossposting=1"

Do not set the upload_phase field in this request.

Sample JSON Response

{
  "success": true
}

Restrictions

You cannot change the permission for the videos that are owned by other Pages.

Allowing Pages not in Business Manager to Crosspost Videos

Graph API v3.2 and Newer

Beginning with Graph API v3.2, you are required to establish a crossposting relationship with another Page. Send a POST request to the {page-id}/begin_crossposting_handshake field. Set allow_live to true to send a request to a Page to create a crossposting relationship a Page can crosspost live videos to your Page without further approval. Set allow_live to false to send a request to create a crossposting relationship wherein a Page can crosspost live videos to your Page only after your admins or editors have approved the video.

Sample Request

curl -X POST \
  "https://graph.facebook.com/{page-a-id}"  \
    -F "access_token={page-a-access-token}" \
    -F "begin_crossposting_handshake= [{"partner_page_id":{page-b-id}, 
                                        "allow_live": true}]"

Sample JSON Response

{"success": true}

For more information about crossposting, visit our Help Center.

Other pages can approve/accept a crossposting relationship by sending a POST request to the {page-id}/accept_crossposting_handshake field and set allow_live to true to accept the request or false to deny it.

Sample Request

curl -X POST \
 https://graph.facebook.com/{page-b-id}"  \
  -F "access_token={page-b-access-token}" \
  -F "accept_crossposting_handshake=
    [{"partner_page_id": {page-a-id}, "allow_live": true}]"

Sample JSON Response

{"success": true}

Graph API v3.1 and Older

For Graph API v3.1 and older, send a POST request to the {page-id}/crossposting_pages edge to establish a crossposting relationship with another page.

Sample Request

curl -X POST \
 "https://graph.facebook.com/{page-a-id}"  \
 -F "access_token={page-a-access-token}" \
 -F "crossposting_pages=
  [{"page_id":{page-b-id}, 
    "allow": true, 
    "action": “NO_ACTION”}]"

Sample JSON Response

{"success": true}

Other pages can approve/accept a crossposting relationship you have requested by sending a POST request to the /{page-id} node and setting crossposting_pages field .

Sample Request

 curl \
-X POST \
"https://graph.facebook.com/{page-b-id}"  \
-F "access_token={PAGE_B_ACCESS_TOKEN}" \
-F "crossposting_pages=
 [{"page_id": {page-a-id}, "allow": true, "action": "{action}"}]"

Sample JSON Response

{"success": true}

Get a list of all the pages that you have requested a crossposting relationship with but haven't yet received a reply. Send a GET request to {page-id}/crosspost_pending_approval_pages field.

Sample Request

curl -X GET \
 "https://graph.facebook.com/{page-a-id}"  \
   -F "access_token={page-a-access-token}" \
   -F "crosspost_pending_approval_pages"

Sample JSON Response

{
  "crosspost_pending_approval_pages": {
    "data": [
      {
        'name': '{Page Name}',
        'id': "{page-id}",
      }
    ]
  }
}

Get a list of all pages that you have established crossposting relationship with (whitelisted) by sending a GET request to the /{page-id}/crosspost_whitelisted_pages field.

Sample Request

curl -X GET \
 "https://graph.facebook.com/{page-a-id}"  \
 -F "access_token={page-a-access-token}" \
 -F "crosspost_whitelisted_pages"

Sample JSON Response

{
  "crosspost_whitelisted_pages": {
    "data": [
      {
        "name": "{Page Name}",
        "id": "{page-id}",
      }
    ]
  }
}

You can turn on and off permission for Pages that you have already shared crossposting permission with to crosspost specific video by sending a POST request to the /{video-id}/allow_crossposting_for_pages field.

Sample Request Granting Permission

curl -X POST \
 "https://graph.facebook.com/{video-c-id}"  \
 -F "access_token={video-c-owner-access-token}" \
 -F "allow_crossposting_for_pages=[{"page_id": {page-b-id}, "allow": true}]"

Sample JSON Response

{"success": true}

Sample Request Denying Permission

curl -X POST \
 "https://graph.facebook.com/{video-c-id}"  \
 -F "access_token={video-c-owner-access-token}" \
 -F "allow_crossposting_for_pages=[{"page_id": {page-b-id}, "allow": false}]"

Sample JSON Response

{"success": true}

You can remove other pages from your crossposting whitelist by sending a POST request to the /{page-id}/crossposting_pages field by setting action to EXPIRE_ALL_CROSSPOSTS_ON_SHARED_ASSETS.

Sample Request to Delete/expire All Previously Crossposted Content

curl -X POST \
 "https://graph.facebook.com/{page-a-id}"  \
 -F "access_token={page-a-access-token}" \
 -F "crossposting_pages=
  [{"page_id": {page-b-id}, "allow": false, "action": "EXPIRE_ALL_CROSSPOSTS_ON_SHARED_ASSETS"}]"

Sample JSON Response

{"success": true}

Create a Slideshow Video

Create a slideshow video using uploaded image URLs.

Supported Image Formats: jpg, jpeg, png, bmp, ico

Note that if the images don't have the same width and height, we will crop and resize them to 600x600px to create a squared video. If the sizes are the same, we will keep the original size for the video.

Limitations

Number of images: 3-7 images with each image being less than 10 MB.

Param

Name Type Description

slideshow_spec

object

An object required for slideshow video.

images_urls

object

A 3-7 element array of the URLs of the images. Required.

duration_ms

number (>0)

The duration in milliseconds of each image. Default value is 1750.

transition_ms

number (>=0)

The duration in milliseconds of the crossfade transition between images. Default value is 250.

Sample Request

curl \
-F 'slideshow_spec={\
     "images_urls":[\
       "https://scontent.xx.fbcdn.net/hads-xtf1/t45.1600-4/11410027_6032434826375_425068598_n.png",\
       "https://scontent.xx.fbcdn.net/hads-xtp1/t45.1600-4/11410105_6031519058975_1161644941_n.png",\
       "http://vignette1.wikia.nocookie.net/parody/images/2/27/Minions_bob_and_his_teddy_bear_2.jpg"\
     ],\
     "duration_ms": 2000,\
     "transition_ms": 200\
   }'\
-F 'access_token=XXXXXXXXXXXXXX' \
"https://graph-video.facebook.com/<API_VERSION>/<PAGE_ID/USER_ID>/videos"

Sample JSON Response

{"id":"video-id"}

Errors

ErrorCode Error Message Recommendation

1363061

You cannot upload both video and images at the same time.

Retry with photos only.

1363064

The images you tried to upload are not enough. The minimum number of images for creating a video is 3.

Retry with more images

1363063

The images you tried to upload are too many. The maximum number of images for creating a video is 7.

Retry with less images.

1363065

Unable to fetch image file from URL.

Retry with valid image url.

1363066

The image file you selected is in a format gif that we don't support.

Remove the unsupported image and retry.

Copyright and Video Files

The Rights Management API tool allows you to upload your files and establish a reference library of content to protect.

PHP Client SDK

If you are using PHP, use the existing PHP client SDK to use chunked uploading without implementing any code. For more details, check out the PHP SDK example.