Graph API

Uploading Photos and publishing Photo stories in Graph API

Using the single photo endpoint you can publish a either a single- or multi- photo post.

Please visit the Page Photos reference doc for information on uploading page photos and publishing scheduled and unscheduled, single and multi-photo posts.

This is useful for developers building apps to post photos and apps that enable people to manage their photos and albums.

Supported Formats

Facebook supports the following formats:

  • JPEG
  • BMP
  • PNG
  • GIF
  • TIFF

Some caveats:

  • If you upload a PNG file, try keep the file size below 1 MB. PNG files larger than 1 MB may appear pixelated after upload.
  • Check the file size of your photos. We recommend uploading photos under 4MB.

Facebook strips all location metadata before publishing and resizes images to different dimensions to best support rendering in multiple sizes.

Permissions

As of April 24,2018, the publish_actions permission has been removed. Please see the Breaking Changes Changelog for more details. To provide a way for your app users to share content to Facebook, we encourage you to use our Sharing products instead.

To upload photos, you need a user access token with publish_actions permission to publish a user post or a page access token with publish_pages and manage_pages permission to publish as a page. You can only post photos to a page as a page.

On May 5, 2020, we released six new Page permissions to replace the manage_pages and publish_pages permissions.

Please visit our V7.0 Blog post, Graph API Changelog, and Pages API Overview for more information.

Publishing a single-photo story

To upload a photo, make a request to /object-id/photos where the /object-id can be a user, page, event or album.

To specify a photo you can use two methods:

  • Provide the URL for the photo with the url parameter
  • Provide a file with the POST request

In this example we provide a url which refers to a .png:

curl -i -X POST \
 -d "url=https://www.facebook.com/images/fb_icon_325x325.png" \
 -d "caption=test photo upload" \
 -d "access_token=<user_photos_user_access_token>" \
 "https://graph.facebook.com/v2.11/me/photos"

You can also make your request in Graph API Explorer. A similar request for the same photo appears as follows:

When uploading a single photo, the photo is immediately posted and the API returns the photo id as well as the post_id for the story:

Try this request out in Graph API Explorer. For more information, see Graph API Reference, Photo.

Publishing a multi-photo story

To publish a multi-photo story for a user, you will make requests to two endpoints:

  1. For each photo in the story, upload it as published=false using the /user-id/photos endpoint.
  2. Publish a multi-photo story using the /user-id/feed endpoint and using the ids returned by uploading an unpublished photo.

1. Uploading an unpublished photo

You can upload an unpublished photo without publishing a story to the /user-id/photos or /page-id/photos edge by making a similar call as described in the single photo post section but by adding the argument published=false. Publishing user photos requires a user access token with user_photos permission. Publishing page photos requires a page access token with manage_pages and publish_pages permissions.

curl -i -X POST \
 -d "url=https://www.facebook.com/images/fb_icon_325x325.png" \
 -d "caption=test photo upload" \
 -d "published=false" \
 -d "access_token=<access_token>" \
 "https://graph.facebook.com/v2.11/me/photos"

You can also make your request in Graph API Explorer. A similar request for the same photo appears as follows:

On successful upload, Graph API provides a response including the id for the upload photo:

{
  "id": "10153677042736789"
}

Using this photo id you can get other information about the asset using our photo read api. Since the parameter published=false was included there is no published story on the user profile or page. After you upload an unpublished photo, Facebook stores it in a temporary upload state, which means it will remain on Facebook servers for about 24 hours. If you do not publish these photos within 24 hours, we delete them.

2. Publishing a multi-photo post with uploaded photos

After you successfully upload all photos, you can publish a multi-photo post using the returned ids by using the /user-id/feed or /page-id/feed endpoint. Here is an example of a request:

curl -i -X POST \
 -d "message=Testing multi-photo post!" \
 -d "attached_media[0]={"media_fbid":"1002088839996"}" \
 -d "attached_media[1]={"media_fbid":"1002088840149"}" \
 -d "access_token=<access_token>" \
 "https://graph.facebook.com/v2.11/me/feed"

This same request appears as follows in Graph API Explorer:

When publishing to a page using the Graph API Explorer the media_fbids must appear as an array in one Value box, [{"media_fbid":"1002088839996"},{"media_fbid":"1002088840149"}] or an error will occur.

On success, Graph API returns the id for the post where the photos are published:

Use the Graph API Explorer to get SDK code snippets of the requests.

If you receive any errors, it's typically because of a permission failure or a bad parameter.