Marketing API Version

Ad Image

Related Topics

You can upload and manage images used in independently of the ad creative. The image formats, sizes and design guidelines depend up on your type of ad, for details, see Ads Guide.


Reading

Image for use in ad creatives can be uploaded and managed independently of the ad itself. The image used in an ad creative can be specified in the following ways:

  • By image hash value of a previously uploaded image.
  • By uploading the image at ad or ad creative creation time.
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription

id

token with structure: ID

The ID of the image

account_id

numeric string

The ad account that owns the image

created_time

datetime

Time the image was created

creatives

list<numeric string>

A list of ad creative IDs that this ad image is being used in. Not applicable for creatives using object_story_spec and a URL in the picture field.

hash

string

The hash which uniquely identifies the image.

height

unsigned int32

The height of the image.

name

string

The filename of the image

original_height

unsigned int32

The height of the image that was originally uploaded.

original_width

unsigned int32

The width of the image that was originally uploaded.

permalink_url

string

A permanent URL of the image to use in story creatives

status

enum {ACTIVE, DELETED}

Status of the image

updated_time

datetime

Time the image was updated

url

string

A temporary URL which the image can be retrieved at. NOTE: do not use this URL in ad creative creation

url_128

string

A temporary URL pointing to a version of the image resized to fit withing a 128x128 pixel box

width

unsigned int32

The width of the image.

Edges

No edges

Creating

You can upload an image or zip file, get back a hash, and use the hash in an ad or creative.

You must include an extension with your filename, e.g. 'sample.jpg' and not just 'sample' or 'sample.tmp', etc.

Examples

Zip file

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

$images = AdImage::createFromZip('<ZIP_PATH>', 'act_<AD_ACCOUNT_ID>');

foreach ($images as $image) {
  echo $image->{AdImageFields::HASH}.PHP_EOL;
}
from facebookads.adobjects.adimage import AdImage

images = AdImage.remote_create_from_zip(
    filename='<IMAGE_ZIP_PATH>',
    parent_id='act_<AD_ACCOUNT_ID>'
)

# Output image hashes.
for image in images:
    print(image[AdImage.Field.hash])
AdImage adImage = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdImage()
  .addUploadFile("filename", new File(<ZIP_PATH>))
  .execute();
curl \
  -F "filename=@test.zip" \
  -F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adimages"

Image file (bmp, jpeg, gif)

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

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

$image->create();
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>'
image.remote_create()

# Output image Hash
print(image[AdImage.Field.hash])
AdImage adImage = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdImage()
  .addUploadFile("filename", new File(<IMAGE_PATH>))
  .execute();
curl \
  -F 'filename=@test.jpg' \
  -F 'access_token=<ACCESS_TOKEN>' \
"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/adimages"

bytes

curl \
  -F 'bytes=iVBORw0KGgoAAAANSUhEUgAAABEAAAARCAMAAAAMs7fIAAAAOVBMVEX///87WZg7WZg7WZg7WZg7WZg7WZg7WZg7WZg7WZg7WZhMeMJEaa5Xi9tKdb0+Xp5Wi9tXjNxThNH+wk/7AAAACnRSTlMAsHIoaM7g/fx9Zr/g5QAAAGlJREFUeNplkFsOwCAIBPGJrtbX/Q/bqm1qwnxuJrBAE6OVD15pQy/WYePsDiIjp9FGyuC4DK7l6pOrVH4s41D6R4EzpJGXsa0MTQqp/yQo8hhHMuApoB1JQ5COnCN3yT6ys7xL3i7/cwMYsAveYa+MxAAAAABJRU5ErkJggg=='
  -F 'access_token=<ACCESS_TOKEN>' \
"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/adimages"

Creating ad with ad creative

Once you have the image hash, you can use the hash in an ad creative.

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdFields;

// First, upload the ad image that you will use in your ad creative
// Please refer to Ad Image Create for details.

// Then, use the image hash returned from above
$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');
$creative->setData(array(
  AdCreativeFields::TITLE => 'My Test Creative',
  AdCreativeFields::BODY => 'My Test Ad Creative Body',
  AdCreativeFields::OBJECT_URL => 'https://www.facebook.com/facebook',
  AdCreativeFields::IMAGE_HASH => '<IMAGE_HASH>',
));

// Finally, create your ad along with ad creative.
// Please note that the ad creative is not created independently, rather its
// data structure is appended to the ad group
$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->setData(array(
  AdFields::NAME => 'My Ad',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => $creative,
));
$ad->create(array(
  Ad::STATUS_PARAM_NAME => Ad::STATUS_PAUSED,
));
from facebookads.adobjects.ad import Ad
from facebookads.adobjects.adcreative import AdCreative

# First, upload the ad image that you will use in your ad creative
# Please refer to Ad Image Create for details.

# Then, use the image hash returned from above
creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.title] = 'My Test Creative'
creative[AdCreative.Field.body] = 'My Test Ad Creative Body'
creative[AdCreative.Field.object_url] = 'https://www.facebook.com/facebook'
creative[AdCreative.Field.image_hash] = '<IMAGE_HASH>'

# Finally, create your ad along with ad creative.
# Please note that the ad creative is not created independently, rather its
# data structure is appended to the ad group
ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = creative
ad.remote_create(params={
    'status': Ad.Status.paused,
})
curl \
  -F 'campaign_id=<AD_SET_ID>' \
  -F 'creative={"title":"test title","body":"test","object_url":"http://www.test.com","image_hash":"8cf726a44ab7008c5cc6b4ebd2491234"}' \
  -F 'name=My ad' \
  -F 'access_token=<ACCESS_TOKEN>' \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads"

Uploading an image during ad or ad creative creation

Alternatively, you can directly upload an image (instead of using an image hash), add the image file to the multi-part MIME POST and specify the file name.

For example, you could specify the following:

curl \
  -F 'campaign_id=<AD_SET_ID>' \
  -F 'creative={"title":"test title","body":"test","object_url":"http:\/\/www.test.com","image_file":"test.jpg"}' \
  -F 'test.jpg=@test.jpg'
  -F 'name=My ad' \
  -F 'access_token=<ACCESS_TOKEN>' \
"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/ads"

The response will contain the following fields:

NameDescription

id

ID of the ad


Copying an image from one ad account to another

To copy an ad image from one account to another, make a POST request to /act_<DESTINATION_ACCOUNT_ID>/adimages with the source account ID (without the act_ prefix) and hash of the image in a copy_from parameter.

curl \
  -F 'copy_from={"source_account_id":"<SOURCE_ACCOUNT_ID>", "hash":"02bee5277ec507b6fd0f9b9ff2f22d9c"}'
  -F 'access_token=<ACCESS_TOKEN>' 
"https://graph.facebook.com/<API_VERSION>/act_<DESTINATION_ACCOUNT_ID>/adimages"

Note: This copies the adimage from the source to the destination account. Your app's user must have access to read the creatives from the source account or you won't be able to copy the images from the account.


You can make a POST request to adimages edge from the following paths:
When posting to this edge, an AdImage will be created.

Parameters

NameDescription
bytes
Base64 UTF-8 encoded string

image file.
bytes = <image content in bytes format>, see example

copy_from
JSON or object-like arrays

This copies the adimage from the source to the destination account.
{"source_account_id":"<SOURCE_ACCOUNT_ID>", "hash":"02bee5277ec507b6fd0f9b9ff2f22d9c"}

source_account_id
numeric string
hash
string
zipbytes
Base64 UTF-8 encoded string

zip file of image

Return Type

Map {
string: Map {
string: Struct {
hash: string,
url: string,
}
}
}

Updating

You can't perform this operation on this endpoint.

Deleting

Examples

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

$image = new AdImage(<IMAGE_ID>, 'act_<AD_ACCOUNT_ID>');
$image->{AdImageFields::HASH} = '<IMAGE_HASH>';
$image->delete();
from facebookads.adobjects.adimage import AdImage

image = AdImage(<IMAGE_ID>, 'act_<AD_ACCOUNT_ID>')
image.remote_delete(params={AdImage.Field.hash: '<IMAGE_HASH>'})
curl -X DELETE \
 -F 'hash=012feg987e98g789f789e87976210983' \
 -F 'access_token=<ACCESS_TOKEN>' \
 "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adimages"

You may only delete ad images that are not currently being used in an ad creative

You can dissociate an AdImage from an AdAccount by making a DELETE request to /act_{ad_account_id}/adimages.

Parameters

NameDescription
hash
string

hash of the image you wish to delete

Required

Return Type

Struct {
success: bool,
}