Marketing API Version

Ad Creative Photo Data

Photo Data is one field within the creative that is used to create photo ads. The Reading section of this document outlines the specific fields within Photo Data. While you cannot create a Photo Data object on its own, you would nest the call within an ad creative creation call.

Note - image_crops is supported with link_data but not with photo_data. This is because Facebook typically renders images from photo posts in full. Facebook also automatically crops based on algoritms designed to improve feed experience. If this is not sufficient, crop your image using image editing software or use link posts.

Create Examples

Create a Photo Ad with utilizing branded content from another page

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativePhotoData;
use FacebookAds\Object\Fields\AdCreativePhotoDataFields;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeFields;

$photo_data = new AdCreativePhotoData();
$photo_data->setData(array(
  AdCreativePhotoDataFields::IMAGE_HASH => '<IMAGE_HASH>',
  AdCreativePhotoDataFields::BRANDED_CONTENT_SPONSOR_PAGE_ID =>
    <SPONSOR_PAGE_ID>,
));

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::PHOTO_DATA => $photo_data,
));

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

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec
from facebookads.adobjects.adcreativephotodata \
    import AdCreativePhotoData

photo_data = AdCreativePhotoData()
photo_data[AdCreativePhotoData.Field.image_hash] = '<IMAGE_HASH>'
photo_data[AdCreativePhotoData.Field.branded_content_sponsor_page_id] = <SPONSOR_PAGE_ID>

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

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'AdCreative for Branded Content Sponsor Ad'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative.remote_create()

print(creative)
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Creative")
  .setObjectStorySpec(
    new AdCreativeObjectStorySpec()
      .setFieldPageId(<PAGE_ID>)
      .setFieldPhotoData(
        new AdCreativePhotoData()
          .setFieldBrandedContentSponsorPageId(<SPONSOR_PAGE_ID>)
          .setFieldCaption("My caption")
          .setFieldImageHash(<IMAGE_HASH>)
      )
  )
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={ 
    "page_id": "<PAGE_ID>", 
    "photo_data": { 
      "branded_content_sponsor_page_id": "<SPONSOR_PAGE_ID>", 
      "image_hash": "<IMAGE_HASH>" 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

Reading

The specification for a photo ad

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription
branded_content_shared_to_sponsor_status
string

The branded content shared to sponsor option

branded_content_sponsor_page_id
numeric string

The branded content sponsor page ID. If your ad promotes branded content, you must use this to indicate the sponsor page. See policy. Your sponsor will be notified and can create an ad using your post. Your sponsor can also see metrics about your ad, including total spend and CPM metrics

branded_content_sponsor_relationship
string

The branded content sponsor relationship option

caption
string

The description of the image

image_hash
string

Hash of an image in your image library with Facebook. Specify this field or url but not both. See Ad Image

page_welcome_message
string

A welcome text from page to user on Messenger once a user performs send message action on an ad

url
string

URL of an image to use in the ad. Specify this field or image_hash but not both. The image specified at the URL will be saved into the ad accounts image library

Edges

No edges

Creating

You can't perform this operation on this endpoint.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.