Upload Files to Facebook with Resumable Upload API

Facebook offers a Resumable Upload API to upload files and use the uploaded media in other API calls. Major advantages includes:

• Based on a resumable protocol and can resume an upload reliably and efficiently without re-uploading the entire file. This is useful for uploading large files (for example, videos and photos) under poor network conditions.
• Allows file data to be processed as soon as they are uploaded.
• Simplifies existing upload flow and is easier use.

Required Knowledge

This guide assumes that you know:

• How to use Facebook's Graph API. To learn more about the Graph API, see Using the Graph API. Requests must be made from a registered app.

• The difference between HTTP requests and HTTP headers. Part of the API adds a parameter in the request, and another part adds it as an HTTP header. Consult your runtime's documentation and HTTP libraries to understand how to set either types before making requests.

Permissions

All API calls must include an access token. No specific Facebook Login Permissions are required to use the file upload part of the API, but posts of photos or videos to a Facebook Page or person's Timeline require video and photo upload permissions. To learn more about permissions see our documentation on Facebook Login Permissions.

API Overview

To use this API, we recommend to use the following flow:

1. Make a POST to the Graph API endpoint /app/uploads to create an upload session. This returns an opaque and unique identifier you can use to upload a file.

2. Make a POST request to the Graph API endpoint /upload:{unique_identifier}, where the {unique_identifier} is replaced by the value returned by the previous call to /app/uploads. This call also requires that you include a file type, a file length, and a zero-based file offset, as described below.

3. Continue to make calls to the upload endpoint until your file is finished uploading. To check the status of an upload, make a GET request to /upload:{unique_identifier}.

4. Once you're finished uploading, use the file handler obtained from the POST call in parts of Facebook's Graph API. For example, you can use it when posting a person's photo or a Page story.

API Details

This section outlines each part of the API process.

Create an Upload Session

The first step to upload a file is to create an upload session and obtain a session ID that will be used in each call as you upload the file or check status of the upload.

To create a new upload session, make a POST call via the /app/uploads endpoint.

The call will look similar to this:

POST /app/uploads?access_token={access_token}&file_length=100&file_type=image/jpeg

The call returns a value that includes the session ID to use in later calls:

{
"id": "upload:MTphdHRhY2htZW50Ojlk2mJiZxUwLWV6MDUtNDIwMy05yTA3LWQ4ZDPmZGFkNTM0NT8=?sig=ARZqkGCA_uQMxC8nHKI"
}

• The file_length and file_type parameters should be in this call, but alternatively may be included when uploading the file data.

• The file_length argument is an unsigned 64 bit integer.

• The file_type argument depends on the intended use of the file, and must be a standard MIME type. Most common file types are supported on those endpoints (eg. image/jpeg, video/mp4, etc).

• The file_name is optional.

---

Upload File Data

Once you get the session ID, you can start uploading file data: Make a POST call to a named endpoint, based on the session ID and was returned via the method described in the previous section.

file_offset is a zero-based offset in bytes to indicate where the upload should resume from. For a new upload session, it should be 0.

See the example below and include the OAuth keyword before your access token.

POST /upload:MTphdHRhY2htZW50Ojlk2mJiZxUwLWV6MDUtNDIwMy05yTA3LWQ4ZDPmZGFkNTM0NT8=?sig=ARZqkGCA_uQMxC8nHKI HTTP/1.1
file_offset: 0
Authorization: OAuth {long access token}
Host: graph.facebook.com
Connection: close

The file data should be attached using standard multipart/form-data according to RFC 2388, which is supported by most HTTP libraries.

If you did not specify file_type and file_length when creating upload session, you need to specify those as query parameters in this call.

When we're done with uploading the data, you'll get a file handle:

{"h":"2:c2FtcGxlLm1wNA==:image/jpeg:GKAj0gAUCZmJ1voFADip2iIAAAAAbugbAAAA:e:1472075513:ARZ_3ybzrQqEaluMUdI"}

This value can be used in place of an uploaded file for subsequent graph calls.

---

Query File Upload Status

You can query status of an upload session by making a GET call to an endpoint that is named based on the ID that was returned via the method described in the previous section.

Just like when uploading data, you must include the access token as an HTTP header.

For example:

GET /upload:MTphdHRhY2htZW50Ojlk2mJiZxUwLWV6MDUtNDIwMy05yTA3LWQ4ZDPmZGFkNTM0NT8=?sig=ARZqkGCA_uQMxC8nHKI HTTP/1.1
Authorization: OAuth {long access token}
Host: graph.facebook.com
Connection: close

The result will be a JSON-encoded ID and offset:

{ "id": "upload:MTphdHRhY2htZW50Ojlk2mJiZxUwLWV6MDUtNDIwMy05yTA3LWQ4ZDPmZGFkNTM0NT8=?sig=ARZqkGCA_uQMxC8nHKI", "file_offset": 0 }

file_offset - 1 is the number of bytes that are already uploaded to the server. In a resume case (eg. your previous upload failed due to connection issue), you should do another POST call and set file_offset to this value.

---

Page Thumbnails

Currently, the only supported use case is for creating a thumbnail when creating a page story.

To do this, you can specify the ID as part of the thumbnail parameter when creating a Page story via the /page/feed edge.

Here's an example of a curl command that creates a page story with a thumbnail:

curl -v -X POST \
-H "Authorization: OAuth {your access token}"
-F "type=image/jpeg" \
"https://graph.facebook.com/me/feed?thumbnail=2:c2FtcGxlLm1wNA==:image/jpeg:GKAj0gAUCZmJ1vodshkjsFADip2AAAbugbAAAA:e:1472075513:ARZ_3ybzrQqEaluMUdI&link=https://www.google.com/search?q=image"