Get Started

This tutorial shows you how to use the Video API to create a Video on a Page. It assumes you know how to perform basic cURL requests with a command-line tool like Terminal, or an app such as Postman, and have basic familiarity with the Graph API Explorer.

Before You Start

You will need:

  • An existing Facebook app. If you don’t have one, go to Facebook for Developers, click My Apps, and create one.
  • A 10MB–20MB video that you have split into 5MB chunks, with all of the chunks in a single directory.
  • A Page that you are able to perform CREATE_CONTENT Tasks on.
  • Access to a command-line tool such as Terminal or an app such as Postman that can perform cURL requests.

Step 1: Get a User Access Token

Normally you will have to implement Facebook Login into your app and use it to get Access Tokens from your app users. However, for this tutorial you can use the Graph API Explorer since it has already implemented Facebook Login and makes it easy for you to generate tokens for any of your apps.

Load the Graph API Explorer and select your app from the Facebook App dropdown menu.

In the User or Page dropdown menu, select Get User Access Token, and continue as yourself and authenticate. If you are reusing an older app, you may already be authenticated.

In the Permissions section, use the Add a permission search field to search for and select the following Permissions:

  • pages_manage_engagement
  • pages_read_user_content

Once you have added the permissions, click the Generate Access Token button. In the modal window that appears, continue as yourself and choose the Page where you eventually want to upload your Video.

Continue through the rest of the screens until you have dismissed the modal. This grants your app the Permissions you’ve selected and also generates a User Access Token.

If you wish, you can click the blue info icon to verify that you have granted your app the correct Permissions (i.e.scopes).

Step 2: Get Your Page ID and Its Token

Using the Graph API Explorer, send a request to the GET /me/accounts edge:

This queries your User and returns any Pages that you authorized your app to access in the last step. Identify your Page in the response and copy its ID (id) and Page Access Token (access_token).

{
  "data": [
    {
      "access_token": "EBACf...",  //Copy your Page Access Token
      "category": "Media",
      "category_list": [
        {
          "id": "163003840417682",
          "name": "Media"
        }
      ],
      "name": "Metricsaurus",
      "id": "1755847768034402",  //Copy your Page ID
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "MTc1NTg0Nzc2ODAzNDQwMgZDZD",
      "after": "MTc1NTg0Nzc2ODAzNDQwMgZDZD"
    }
  }
}

Step 3: Create a Video Session

In your command-line tool, navigate to the folder containing your video’s chunks, then send a cURL request to the POST /page-id/videos edge on the graph-video.facebook.com host. If you are using Postman, include the query parameter keys and values in the request Body as form-data.

Sample Request

curl -X POST \
  "https://graph-video.facebook.com/1755847768034402/videos" \
  -F "access_token=EBACf..." \
  -F "upload_phase=start" \
  -F "file_size=77188035"

Replace the Page ID (1755847768034402) in the request path with your Page's ID, set access_token to the Page Access Token you just copied, and file_size to the video file’s total size, in bytes.

The API will return a Video Session:

{
  "video_id": "225467151853466",
  "start_offset": "0",
  "end_offset": "1048576",
  "upload_session_id": "225467155186799"
}

Copy all returned values, except for end_offset.

Step 4: Upload First Video Chunk

Send another request to the POST /{page-id}/videos edge and include your upload_session_id and the name of your first video chunk.

Sample Request

curl -X POST \
  "https://graph-video.facebook.com/1755847768034402/videos" \
  -F "access_token=EBACf..." \
  -F "upload_phase=transfer" \
  -F "start_offset=0" \
  -F "upload_session_id=225467155186799" \
  -F "video_file_chunk=@xaa"

If you are using cURL, make sure to include the @ symbol before your file name. If you are using Postman, omit the @ symbol, set the video_file_chunk parameter to File (mouseover the row to trigger the dropdown menu) and manually select the first chunk file.

The API will respond with a new start_offset. Capture the new value.

{
  "start_offset": "10485760",
  "end_offset": "15728640"
}

Step 5: Upload Remaining Video Chunks

Perform the same request, but set start_offset to the new start_offset value returned in the previous response, and set video_file_chunk to the name of the next video chunk in sequence.

curl -X POST \
  "https://graph-video.facebook.com/1755847768034402/videos" \
  -F "access_token=EBACf..." \
  -F "upload_phase=transfer" \
  -F "start_offset=10485760" \
  -F "upload_session_id=225467155186799" \
  -F "video_file_chunk=@xab"

The API will once again respond with a new start_offset value which you can use to upload the next chunk in sequence.

{
  "start_offset":"15728640",
  "end_offset":"20971520"
}

Continue repeating this step until you have uploaded all remaining video chunks. Make sure that you are uploading your chunks in the correct order. The program you used to split your video file into chunks should take care of naming your chunks in sequential order.

Step 6: End Upload Session

Once you have uploaded your final chunk, end the upload session by sending one final request to the same endpoint and set upload_phase to finish.

Sample Request

curl -X POST \
  "https://graph-video.facebook.com/1755847768034402/videos"  \
  -F "access_token=EBACf..." \
  -F "upload_phase=finish" \
  -F "upload_session_id=225467155186799"

Upon success, the API will end the upload session and respond with true.

{
  "success": true
}

We will assemble your video and encode it. The encoding process may take up to several minutes to fully encode, depending on the total size of your video file.