Marketing API Version

Image Crops

Related Topics

Image crops are used to describe the way that an image should be displayed in each aspect ratio of the different ad placements. During rendering, the image will be cropped according to the specifications given, and if no specification is provided for a certain aspect ratio, the image will be displayed in the default way.

Cropping information is optional for all ads, but if cropping is specified, it should be specified for all placements that the ad could appear in. For example, if cropping is specified for Right Hand Column but the ad is also desired to be displayed in Newsfeed, then cropping should be provided for the Newsfeed placement as well. Right now image crops are only supported for ad creatives that support the image_file or image_hash parameters. Page posts are not supported right now.

Image crops are comprised of key-value pairs, where the key is a crop key and the value is the pixel dimensions of the crop, specified as a set of (x, y) coordinates of the upper-left and bottom-right corners of the crop rectangle. A crop key describes an aspect ratio.

The list of keys accepted can be found with Ads Image Crops reference doc.

Values are specified as a two-dimensional JSON array, or an array of two (x, y) tuples. The aspect ratio of the box specified (width/height) must be as close as possible to the aspect ratio of the corresponding crop key.

For cropping, the origin of the image (0, 0) is at the upper-left corner, and the point (width - 1, height - 1) is at the bottom-right corner.

Values must adhere to the following constraints:

  • Points specified by (x, y) must lie within the image. A rectangle that extends beyond the bounds of the image is considered invalid.
  • The rectangle must be the same aspect ratio as specified by the crop key.
  • Coordinates must not contain negative values.


   "191x100": [ [100, 10], [433, 184] ],
   "100x72": [ [160, 20], [371, 172] ]


First, upload the ad image that you will use in your ad creative:

use FacebookAds\Object\AdImage;
use FacebookAds\Object\Fields\AdImageFields;

$image = new AdImage(null, 'act_<AD_ACCOUNT_ID>');
$image->{AdImageFields::FILENAME} = '<IMAGE_PATH>';

echo 'Image Hash: '.$image->{AdImageFields::HASH}.PHP_EOL;
from facebookads.adobjects.adimage import AdImage

image = AdImage(parent_id='act_<AD_ACCOUNT_ID>')
image[AdImage.Field.filename] = '<IMAGE_PATH>'

# Output image Hash
AdImage adImage = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdImage()
  .addUploadFile("filename", new File(<IMAGE_PATH>))
curl \
  -F 'filename=@<IMAGE_PATH>' \
  -F 'access_token=<ACCESS_TOKEN>' \<AD_ACCOUNT_ID>/adimages

Then, create an ad creative by referencing the image hash returned in the previous call:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeFields;

$link_data = new AdCreativeLinkData();
  AdCreativeLinkDataFields::MESSAGE => 'Ad message',
  AdCreativeLinkDataFields::LINK => '<URL>',
  AdCreativeLinkDataFields::CAPTION => 'Ad caption',
  AdCreativeLinkDataFields::IMAGE_HASH => '<IMAGE_HASH>',
  AdCreativeLinkDataFields::IMAGE_CROPS => array(
    '191x100' => array(
      array(100, 10),
      array(433, 184),
    '100x72' => array(
      array(160, 20),
      array(371, 172),

$object_story_spec = new AdCreativeObjectStorySpec();
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

  AdCreativeFields::NAME => 'Image crop creative',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,

from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativelinkdata import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec

link_data = AdCreativeLinkData()
link_data[AdCreativeLinkData.Field.message] = 'Ad message'
link_data[] = '<URL>'
link_data[AdCreativeLinkData.Field.caption] = 'Ad caption'
link_data[AdCreativeLinkData.Field.image_hash] = '<IMAGE_HASH>'
link_data[AdCreativeLinkData.Field.image_crops] = {
    '191x100': [
        [100, 10],
        [433, 184],
    '100x72': [
        [160, 20],
        [371, 172],

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.link_data] = link_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[] = 'Image crop creative'
creative[AdCreative.Field.object_story_spec] = object_story_spec
curl \
  -F 'name=Image crop creative' \
  -F 'object_story_spec={ 
    "link_data": { 
      "caption": "Ad caption", 
      "image_crops": {"191x100":[[100,10],[433,184]],"100x72":[[160,20],[371,172]]}, 
      "image_hash": "<IMAGE_HASH>", 
      "link": "<URL>", 
      "message": "Ad message" 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \<AD_ACCOUNT_ID>/adcreatives