Image Crops

Provide aspect ratios for images in different ad placements. Facebook crops your image according to your specifications given or if you provide no cropping we display it using defaults. See Ad Image. For example upload an image to use in 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, provide ad creative by referencing the image hash returned in the previous call along with cropping:

curl -X POST \ -F 'name="Image crop creative"' \ -F 'object_story_spec={ "page_id": "<PAGE_ID>", "link_data": { "image_crops": { "100x100": [ [ 0, 0 ], [ 100, 100 ] ] }, "image_hash": "<IMAGE_HASH>", "link": "<URL>", "message": "Ad message" } }' \ -F 'access_token=<ACCESS_TOKEN>' \<AD_ACCOUNT_ID>/adcreatives
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const AdCreative = bizSdk.AdCreative; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_ACCOUNT_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'Image crop creative', 'object_story_spec' : {'page_id':'<pageID>','link_data':{'image_crops':{'100x100':[[0,0],[100,100]]},'image_hash':'<imageHash>','link':'<url>','message':'Ad message'}}, }; const adcreatives = (new AdAccount(id)).createAdCreative( fields, params ); logApiCallResult('adcreatives api call complete.', adcreatives);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\AdCreative; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_ACCOUNT_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'Image crop creative', 'object_story_spec' => array('page_id' => '<pageID>','link_data' => array('image_crops' => array('100x100' => array(array(0,0),array(100,100))),'image_hash' => '<imageHash>','link' => '<url>','message' => 'Ad message')), ); echo json_encode((new AdAccount($id))->createAdCreative( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.adcreative import AdCreative from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'Image crop creative', 'object_story_spec': {'page_id':'<pageID>','link_data':{'image_crops':{'100x100':[[0,0],[100,100]]},'image_hash':'<imageHash>','link':'<url>','message':'Ad message'}}, } print AdAccount(id).create_ad_creative( fields=fields, params=params, )
import*; import; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_ACCOUNT_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createAdCreative() .setName(\"Image crop creative\") .setObjectStorySpec( new AdCreativeObjectStorySpec() .setFieldLinkData( new AdCreativeLinkData() .setFieldImageCrops( new AdsImageCrops() .setField100x100(Arrays.asList(Arrays.asList(0, 0), Arrays.asList(100, 100))) ) .setFieldImageHash(\"<imageHash>\") .setFieldLink(\"<url>\") .setFieldMessage(\"Ad message\") ) .setFieldPageId(\"<pageID>\") ) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) adcreatives = ad_account.adcreatives.create({ name: 'Image crop creative', object_story_spec: {'page_id':'<pageID>','link_data':{'image_crops':{'100x100':[[0,0],[100,100]]},'image_hash':'<imageHash>','link':'<url>','message':'Ad message'}}, })

Crops contains key-value pairs, where the key is a crop key and value is the pixel dimensions of the crop. For all supported keys, see Ads Image Crops Reference.

Provide value as (x, y) coordinates for the upper-left and bottom-right corners of the cropping rectangle. crop key describes an aspect ratio. The aspect ratio of the box specified by width and height must be as close as possible to the aspect ratio in crop key.

An image's origin (0, 0) is at the upper-left corner. The point, (width - 1, height - 1) is at the bottom-right corner.


When you use this feature, you should use it for all placements where an ad may appear. For example, if you provide it for the Right Hand Column, and you also want to use the ad in Newsfeed, you'll need to provide cropping for the Newsfeed placement.


Image crops are only supported for ad creatives with image_file or image_hash. Page posts are not supported. Values must adhere to these constraints:

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

For example:

Example:{"100x100": [ [330, 67], [1080, 817] ]}