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, 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).

Non-Resumable Upload

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

  • Send multi-part HTTP request with the video source.
  • Provide 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.

For full list of parameters and actions that video support, see Graph API Reference, Video and the video publish endpoints:

Resumable Upload

In Graph API v2.3 we introduce a resumable upload protocol. You can now upload videos as chunks, handle errors and resume the upload of the remaining chunks. The protocol has 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.

Limitations - Resumable upload supports uploading videos that are up to 1.75GB and 45 minutes long.

For full list of parameters and actions that video support, see Graph API Reference, Video and the video publish endpoints:

Initialize the Upload Session

Start Phase. You start a resumable upload by initializing a session. To make a start request and create a video upload session, make a POST request with the parameter upload_phase(enum)=start to the /{page_id || user_id || event_id || group_id}/videos edge.

The request parameters are:

  • upload_phase (enum) - Set to start
  • file_size (int32) - The size of the file in bytes

The server response includes the following:

  • upload_session_id (int32) - ID of the upload session
  • video_id (int32) - ID of the video
  • start_offset (int32) - Start byte position of the first chunk to send. Will be 0
  • end_offset (int32) - End byte position of the next file chunk to send

For example, to upload upload a big file the_sample_file.mp4, which is 152043520 bytes. The first request initializes an upload session and tells the server the video size:

curl \
-X POST \
"https://graph-video.facebook.com/v2.3/1533641336884006/videos"  \
-F "access_token=XXXXXXXXX" \
-F "upload_phase=start" \
-F "file_size=152043520"

The response from server specifies the first chunk to upload:

{"upload_session_id":"1564747013773438","video_id":"1564747010440105","start_offset":"0","end_offset":"52428800"}

Here the server wants you to upload [0, 52428800] part of the_sample_fle.mp4. To do this, you would need to slice the file to chunks according to the start and end offsets, and send those chunks with transfer requests.

Upload the video in 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.

You can split the video with the UNIX command split -b{X}m {filename} this will split {filename} into multiple parts which are X MB each.

The request parameters are:

  • upload_phase (enum) - Set to transfer
  • upload_session_id (int32) - The session id returned in the start phase
  • start_offset (int32) - Start byte position of this chunk
  • video_file_chunk (multipart/form-data) - The video chunk, encoded as form data

This server response includes:

  • start_offset (int32) - Start byte position of the next file chunk
  • end_offset (int32) - End byte position of the next file chunk

For example, to send our first chunk starting from offset 0:

curl \
 -X POST \
 "https://graph-video.facebook.com/v2.3/1533641336884006/videos"  \
 -F "access_token=XXXXXXX" \
 -F "upload_phase=transfer" \
 -F “start_offset=0" \
 -F "upload_session_id=1564747013773438" \
 -F "video_file_chunk=@chunk1.mp4"

On success, the server sends a response indicating the start and endpoints for the next chunk to send:

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

Now you should cut and upload the second chunk with range [52428800, 104857601] from the_sample_fle.mp4. Here we upload it as chunk2.mp4:

curl \
-X POST \
"https://graph-video.facebook.com/v2.3/1533641336884006/videos"  \
-F "access_token=XXXXXXX" \
-F "upload_phase=transfer" \
-F "start_offset=52428801" \
-F "upload_session_id=1564747013773438" \
-F "video_file_chunk=@chunk2.mp4"

On success, the server sends a response with the start and endpoints for the next chunk to send:

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

Now you should cut and upload the third chunk with range [104857601, 152043520] from the_sample_fle.mp4. Here we upload it as chunk3.mp4:

curl \
 -X POST \
 "https://graph-video.facebook.com/v2.3/1533641336884006/videos"  \
 -F "access_token=XXXXXXX" \
 -F "upload_phase=transfer" \
 -F "start_offset=104857601" \
 -F "upload_session_id=1564747013773438" \
 -F "video_file_chunk=@chunk3.mp4"

After successful upload of this chunk, the server sends this response:

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

At this point, the server reponse 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 occured. For more information about errors, see:

Post the Video

Once you upload all chunks, you need to 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/v2.3/1533641336884006/videos"  \
-F "access_token=XXXXXXXX" \
-F "upload_phase=finish" \
-F "upload_session_id=1564747013773438" 

On success, Graph API returns JSON object with a success field with the value true, for example:

{"success":true}

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

Subscribe and get notified when the video is ready

You can subscribe to real-time updates to a callback url when video processing is done, and your video's ready to use. However, updates will not be 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. See Receiving API Updates in Real-Time

The /videos field contains the 'status' sub-field, and the value is either ready if video processing succeeded or ERROR if it failed. See Graph API Reference, Video Status.

Publish Videos with Thumbnails

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

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

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

Restrictions

You must selet a thumbnail image from the main video content; it 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.

Related Guides

Crossposted Videos

Upload using Crossposted Videos

From Graph API v2.6, you can 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.

You have to use the parameter crossposted_video_id to specify the video from which the new post has to be created. To know whether your video can be used for creating crossposts, you can use the field is_crossposting_eligible on the Graph API for Videos. You can also use videos from other Pages in your Business Manager to create crossposts if you have permission. To get the list of videos from other Pages that are available for crossposting, you can use the edge videos_you_can_use on the Graph API for Pages.

Restrictions

You have to use crossposted_video_id parameter without specifying any upload_phase.

For example, to create a new post from an existing video:

curl \
-X POST \
"https://graph-video.facebook.com/v2.6/1533641336884006/videos"  \
-F "access_token=XXXXXXX" \
-F "crossposted_video_id=1576050132712388"

On success, the server will send the new video id in the response.

{"id":"1577837922533609"}

Allowing other Pages to Crosspost Videos

You can allow other pages managed by the same Business as you to crosspost your video using allow_bm_crossposting field on the Video API. You cannot change the permission for the videos that are owned by other Pages.

For example, to enable crossposting permissions on an existing video:

 curl \
-X POST \
"https://graph-video.facebook.com/v2.6/1533641336884006"  \
-F "access_token=XXXXXXX" \
-F "allow_bm_crossposting=1"

On success, the server will send the statusf in the response.

{
  "success": true
}

Resumable Upload Errors

Initialize an Upload Session, start phase:

error_subcode Error Error Recommendations

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

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.

Upload with small file or talk to Facebook for capacity

1363022

CodedException

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.

Make sure your file is not empty.


Upload chunks, transfer phase:

Error Code Error Message Recommendations

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:

ErrorCode Error Message Recommendation

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.

1611177

Not allowed to attach action to container: You do not have permission to publish an action with the container number

Make sure your access token has publish_actions permission

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.

Generate Image Slideshows Video

As of 2.5, user/page can now 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 600*600px to create a squared video. But if the sizes are the same, we will keep the original size for the video.

Limitations Number of images: 3-7 images, each image should be 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.

Example

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"

The response will be the new video ID:

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

For php developer, they can use existing php client sdk to use chunked uploading without implementing any code in their side.

For more details, check out the PHP SDK