图谱 API 版

Ad, Image

Upload and manage images to later use in ad creative. Image formats, sizes and design guidelines depend up on your type of ad, see Ads Guide. See Image Crop and Ads Guide.

For example, provide an image file such as .bmp, .jpeg, or .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=@<IMAGE_PATH>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adimages

Once you have the image hash, you can use in 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 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={ 
    "title": "My Test Creative", 
    "body": "My Test Ad Creative Body", 
    "object_url": "https:\/\/www.facebook.com\/facebook", 
    "image_hash": "<IMAGE_HASH>" 
  }' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/ads

读取

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.

Examples

By Ad Account

Get available images for an ad account. Images used in every creative for the account should appear in the list.

use FacebookAds\Object\AdAccount;

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$images = $account->getAdImages();

from facebookads.adobjects.adaccount import AdAccount

account = AdAccount('act_<AD_ACCOUNT_ID>')
images = account.get_ad_images()

APINodeList<AdImage> adImages = new AdAccount(act_<AD_ACCOUNT_ID>, context).getAdImages()
  .execute();

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adimages

By Image

To get specific images, specify hashes of the images in a hashes:

use FacebookAds\Object\AdAccount;

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$images = $account->getAdImages(
  array(),
  array(
    'hashes' => array(
      '<IMAGE_1_HASH>',
      '<IMAGE_2_HASH>',
    ),
  ));

from facebookads.adobjects.adaccount import AdAccount

account = AdAccount('act_<AD_ACCOUNT_ID>')
params = {
    'hashes': [
        <IMAGE_1_HASH>,
        <IMAGE_2_HASH>,
    ],
}
images = account.get_ad_images(params=params)

APINodeList<AdImage> adImages = new AdAccount(act_<AD_ACCOUNT_ID>, context).getAdImages()
  .setHashes("[\"" + <IMAGE_1_HASH> + "\",\"" + <IMAGE_2_HASH> + "\"]")
  .execute();

curl -G \
  -d 'hashes=["<IMAGE_1_HASH>","<IMAGE_2_HASH>"]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adimages

参数

这个端点不包含任何参数。

字段

字段	描述
`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.
`is_associated_creatives_in_adgroups` bool	SELF_EXPLANATORY
`name` string	The filename of the image. The maximum length of this string is 100 characters.
`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, INTERNAL, 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. 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 within a 128x128 pixel box
`width` unsigned int32	The width of the image.

错误代码

错误	描述
2635	You are calling a deprecated version of the Ads API. Please update to the latest version.

创建

Upload an image or zip file, get back a hash, and use the hash in an ad or creative. You must include a filename extension such as sample.jpg, not sample or sample.tmp.

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=@<ZIP_PATH>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_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"

Upload an Image on Create

You can upload an image instead of using an image hash when you create an ad or ad creative. Add the image file to the multi-part MIME POST and specify the file name. For example:

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 contains:

Name	Description
id	ID of the ad

Copying Images

To copy an ad image from one account to another, make a POST request to /act_{DESTINATION_ACCOUNT_ID}/adimages. Provide the source account ID without the act_ prefix and a hash of the image in copy_from. This copies the image from the source to the destination account. Your app's user must have access to read the creatives from the source account or you cannot copy images from the account.

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"

你可以通过下列路径向 adimages 连线发出 POST 请求：

/act_{ad_account_id}/adimages

发布到这个连线会创建 an AdImage 。

参数

参数	描述
`bytes` Base64 UTF-8 string	Image file. Example: `bytes = <image content in bytes format>`
`copy_from` JSON or object-like arrays	This copies the Ad Image from the source to the destination account. `{"source_account_id":"<SOURCE_ACCOUNT_ID>"`, `"hash":"02bee5277ec507b6fd0f9b9ff2f22d9c"}`
`source_account_id` numeric string
`hash` string

返回类型

这个端点支持先写后读，并会读取返回类型中 images 代表的节点。

Map {

string: Map {

string: Struct {

hash: string,

url: string,

url_128: string,

url_256: string,

url_256_height: string,

url_256_width: string,

height: int32,

width: int32,

name: string,

}

错误代码

错误	描述
100	Invalid parameter
80004	There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#ads-management.
200	Permissions error
368	The action attempted has been deemed abusive or is otherwise disallowed
190	Invalid OAuth 2.0 Access Token
415	Two factor authentication required. User have to enter a code from SMS or TOTP code generator to pass 2fac. This could happen when accessing a 2fac-protected asset like a page that is owned by a 2fac-protected business manager.

更新

你无法在此端点执行该操作。

删除

You can only delete ad images not currently being used in an ad creative.

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

$image = new AdImage(<IMAGE_ID>, 'act_<AD_ACCOUNT_ID>');
$image->{AdImageFields::HASH} = '<IMAGE_HASH>';
$image->deleteSelf();

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 \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adimages

你可以向 /act_{ad_account_id}/adimages 发出 DELETE 请求，将 an AdImage 与 an AdAccount 取消关联。

参数

参数描述

参数	描述
`hash` string	Hash of the image you wish to delete. 必填

hash

string

Hash of the image you wish to delete.

必填

返回类型

Struct {

success: bool,

}

错误代码

错误	描述
100	Invalid parameter