Facebook offers a Resumable Upload API to upload files and use the uploaded media in other API calls. Major advantages includes:
This document assumes that you know how to use Facebook's Graph API. To learn more about the Graph API, please see our guide on Using the Graph API. Requests must be made from a registered app.
This document also assumes you know 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. Please consult your runtime's documentation and HTTP libraries to understand how to set either types before making requests.
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.
In order to use this API, you should use the following flow:
/app/uploads to create an upload session. This will return an opaque and unique identifier you can use to upload a file./upload:{unique_identifier}, where the {unique_identifier} is replaced by the value returned by the previous call to /app/uploads. This call will also require that you include a file type, a file length, and a zero-based file offset, as described below./upload:{unique_identifier} and it will return information about the upload.This section covers each part of the API in detail.
The first step to upload a file is to create an upload session and obtain session ID which will be used in each call as you upload the file or check status of the upload.
The way to create a new upload session is making a POST call via the /app/uploads endpoint. The call will look something like this:
POST /app/uploads?access_token={access_token}&file_length=100&file_type=image/jpeg
The call will return a value that includes the session ID that you should use in later calls (This is server generated and you should NEVER modify it):
{
"id": "upload:MTphdHRhY2htZW50Ojlk2mJiZxUwLWV6MDUtNDIwMy05yTA3LWQ4ZDPmZGFkNTM0NT8=?sig=ARZqkGCA_uQMxC8nHKI"
}
The parameters file_length and file_type 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.
Once you get the session ID, you can start uploading file data. You do this by making a POST call to an endpoint that is named based on the session ID that was returned via the method described in the previous section.
The file_offset parameter must be included as an HTTP header. It will not work as a query parameter. 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).
In addition, the access token must be included in an Authorization HTTP header. It will not work as a query parameter. Please 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.
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.
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"