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 10–20 MB video that you have split into 5 MB 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

As a general practice, you 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 because it has already implemented Facebook Login and makes it easy for you to generate tokens for any of your apps.

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

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

  3. In the Permissions section, use the Add a permission search field to search for and select the following permissions: pages_manage_engagement and pages_read_user_content.
  4. Click Generate Access Token.
  5. In the modal window that appears, continue as yourself and choose the Page where you eventually want to upload your video.
  6. Continue Next through the rest of the screens until you dismiss the modal. This grants your app the permissions you’ve selected and also generates a user access token.
  7. Optional. Click the blue info icon to verify that you have granted your app the correct permissions (scopes).

Step 2: Get Your Page ID and Its Token

  1. 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.
  2. Identify your Page in the response and copy its ID (id) and Page access token (access_token).
  3. {
      "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

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

  2. Sample Request
    curl -X POST \
      "https://graph-video.facebook.com/1755847768034402/videos" \
      -F "access_token=EBACf..." \
      -F "upload_phase=start" \
      -F "file_size=77188035"
    
  3. 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.

  4. The API returns a video session:
    {
      "video_id": "225467151853466",
      "start_offset": "0",
      "end_offset": "1048576",
      "upload_session_id": "225467155186799"
    }
    
  5. 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, include the @ symbol before your file name.

If you are using Postman, omit the @ symbol, set video_file_chunk to File (hover over the row to trigger the drop-down 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

  1. 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.
  2. 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"
    }
    
  3. Continue repeating this step until you have uploaded all remaining video 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.