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. Currently we support publishing multi-photo posts for a User only.

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

To upload photos associated with a user, you need the publish_actions permission.

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%3A%2F%2Fwww.facebook.com%2Fimages%2Ffb_icon_325x325.png" \
 -d "caption=test%20photo%20upload" \
 -d "access_token=<user_photos_token>" \
 "https://graph.facebook.com/v2.4/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

Currently we support publishing batch photos for the User object only. To publish a multi-photo story, you will make requests to two endpoints:

  1. for each photo in the story upload it unpublished using the {user-id}/photos endpoint
  2. then, publish a multi-photo story using the {user-id}/feed endpoint and using the ids returned by uploading a photo

1. Uploading an unpublished photo

You can upload a unpublished photo without publishing a story to the {user-id}/photos edge by making a similar call as described in the single photo post section but by adding the argument published=false.

curl -i -X POST \
 -d "url=https%3A%2F%2Fwww.facebook.com%2Fimages%2Ffb_icon_325x325.png" \
 -d "caption=test%20photo%20upload" \
 -d "published=false" \
 -d "access_token=<user_photos_token>" \
 "https://graph.facebook.com/v2.4/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. 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 endpoint. Here is an example of a request:

curl -i -X POST \
 -d "message=Testing%20multi-photo%20post!" \
 -d "attached_media%5B0%5D=%7B%22media_fbid%22%3A%221002088839996%22%7D" \
 -d "attached_media%5B1%5D=%7B%22media_fbid%22%3A%221002088840149%22%7D" \
 -d "access_token=<publish_actions_token>" \
 "https://graph.facebook.com/v2.4/me/feed"

This same request appears as follows in Graph API Explorer:

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

To make the same publish request with the PHP SDK:

 $request = new FacebookRequest(
  $session,
  'POST',
  '/me/feed',
  array(
    'message' => 'Testing multi-photo post!',
    'attached_media[0]' => '{"media_fbid":"1002088839996"}',
    'attached_media[1]' => '{"media_fbid":"1002088840149"}'
  )
);

$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */

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