meta-api-reference

Meta Marketing API - 完整参考

配置

• API 版本： v22.0
• 基础 URL： https://graph.facebook.com/v22.0/
• .env 中的两个令牌：
  • ADS_MANAGER_ACCESS_TOKEN - Marketing API（广告系列管理、成效分析、报告）
  • AD_LIBRARY_ACCESS_TOKEN - Ad Library API（竞争对手研究）
• 令牌过期时间： 距上次刷新约 60 天（查看 .env 注释中的日期）

---

账户层级

Ad Account (act_XXXX)
  -> Campaign (objective, budget if CBO, bid strategy)
    -> Ad Set (targeting, budget if ABO, optimization, schedule)
      -> Ad (creative reference, status)
        -> Ad Creative (media, copy, CTA, url_tags)

---

广告系列架构

端点： POST /{account_id}/campaigns

必填字段

字段	类型	说明
name	string	广告系列名称
objective	enum	营销目标（ODAX 框架）
status	enum	广告系列状态
special_ad_categories	array	特殊类别声明（如果没有则传入 []）

可选字段

字段	类型	说明
daily_budget	int (cents)	CBO 每日预算（5000 = $50.00）
lifetime_budget	int (cents)	CBO 总预算
bid_strategy	enum	出价策略
buying_type	enum	购买类型
is_adset_budget_sharing_enabled	string	CBO 使用 "true"，ABO 使用 "false"
execution_options	array	["validate_only"] 或 ["include_recommendations"]

目标（ODAX 框架）

值	说明	适用阶段
OUTCOME_AWARENESS	品牌认知度、覆盖人数	漏斗顶部
OUTCOME_ENGAGEMENT	帖子互动、视频观看、主页赞	漏斗中部
OUTCOME_TRAFFIC	链接点击、落地页浏览	漏斗中部
OUTCOME_LEADS	潜在客户开发表单、转化（潜在客户）	漏斗底部
OUTCOME_SALES	转化（购买）、目录销售	漏斗底部
OUTCOME_APP_PROMOTION	应用安装、应用互动	应用广告系列

旧版目标（新建广告系列时已弃用，API 对旧广告系列仍会返回）：CONVERSIONS、LEAD_GENERATION、LINK_CLICKS、BRAND_AWARENESS、REACH、POST_ENGAGEMENT、VIDEO_VIEWS、MESSAGES、APP_INSTALLS、PAGE_LIKES、EVENT_RESPONSES、STORE_VISITS、PRODUCT_CATALOG_SALES

出价策略

值	说明
LOWEST_COST_WITHOUT_CAP	最低成本，无上限（默认）
COST_CAP	成本上限——设置单次结果的最高成本
LOWEST_COST_WITH_BID_CAP	出价上限——设置每次竞价的最高出价
LOWEST_COST_WITH_MIN_ROAS	最低 ROAS——设定最低回报目标

特殊广告类别

值	说明
CREDIT	信贷优惠
EMPLOYMENT	工作机会
HOUSING	住房／房地产
ISSUES_ELECTIONS_POLITICS	社会议题、选举、政治
FINANCIAL_PRODUCTS_SERVICES	金融产品
ONLINE_GAMBLING_AND_GAMING	赌博／游戏
NONE	无特殊类别

购买类型

值	说明
AUCTION	标准竞价购买（默认，99% 的情况下使用）
RESERVED	预留／保证投放（覆盖人数与频次）

广告系列状态

ACTIVE、PAUSED、DELETED、ARCHIVED

CBO 与 ABO

CBO（广告系列预算优化）：

• 在广告系列上设置 daily_budget 或 lifetime_budget
• 在广告系列上设置 is_adset_budget_sharing_enabled: "true"
• 不要在广告组上设置预算
• Meta 会自动在各广告组之间分配预算

ABO（广告组预算优化）：

• 在广告系列上设置 is_adset_budget_sharing_enabled: "false"
• 在每个广告组上设置 daily_budget 或 lifetime_budget
• 不要在广告系列上设置预算
• 每个广告组都有自己的独立预算

---

广告组架构

端点： POST /{account_id}/adsets

必填字段

字段	类型	描述
name	字符串	广告组名称
campaign_id	字符串	父级广告系列 ID
optimization_goal	枚举	优化目标
billing_event	枚举	计费时机
targeting	JSON 对象	定向规范
status	枚举	广告组状态
daily_budget 或 lifetime_budget	int（美分）	预算（仅限 ABO）

可选字段

字段	类型	描述
bid_amount	int（美分）	出价金额（cost_cap 或 bid_cap 必填）
bid_strategy	枚举	覆盖广告系列出价策略
start_time	ISO 8601	开始投放时间
end_time	ISO 8601	停止投放时间
promoted_object	JSON 对象	用于转化优化的 Pixel/事件
destination_type	枚举	广告将用户引导至何处
is_dynamic_creative	bool	启用动态创意
pacing_type	数组	["standard"] 或 ["day_parting"]
dsa_beneficiary	字符串	DSA 合规信息——受益方名称（EU）
dsa_payor	字符串	DSA 合规信息——付款方名称（EU）
targeting_automation	JSON 对象	Advantage+ 受众设置

优化目标（34 个值）

最常用：

值	适用目标	描述
OFFSITE_CONVERSIONS	OUTCOME_LEADS、OUTCOME_SALES	通过 Pixel 跟踪的网站转化
LEAD_GENERATION	OUTCOME_LEADS	平台内潜在客户表单提交
LINK_CLICKS	OUTCOME_TRAFFIC	链接点击
LANDING_PAGE_VIEWS	OUTCOME_TRAFFIC	落地页浏览量（需要 Pixel）
REACH	OUTCOME_AWARENESS	最大独立触达人数
IMPRESSIONS	OUTCOME_AWARENESS	最大展示次数
AD_RECALL_LIFT	OUTCOME_AWARENESS	广告回想度优化
POST_ENGAGEMENT	OUTCOME_ENGAGEMENT	帖子互动
PAGE_LIKES	OUTCOME_ENGAGEMENT	主页赞
THRUPLAY	OUTCOME_ENGAGEMENT	视频观看（15 秒以上）
VALUE	OUTCOME_SALES	转化价值（ROAS）
APP_INSTALLS	OUTCOME_APP_PROMOTION	应用安装
CONVERSATIONS	OUTCOME_LEADS	消息对话
QUALITY_LEAD	OUTCOME_LEADS	优质潜在客户（针对 CRM 优化）

完整列表（其他值）： ADVERTISER_SILOED_VALUE、APP_INSTALLS_AND_OFFSITE_CONVERSIONS、AUTOMATIC_OBJECTIVE、DERIVED_EVENTS、ENGAGED_USERS、EVENT_RESPONSES、IN_APP_VALUE、MEANINGFUL_CALL_ATTEMPT、MESSAGING_APPOINTMENT_CONVERSION、MESSAGING_PURCHASE_CONVERSION、NONE、PROFILE_AND_PAGE_ENGAGEMENT、PROFILE_VISIT、QUALITY_CALL、REACH、REMINDERS_SET、SUBSCRIBERS、VISIT_INSTAGRAM_PROFILE

计费事件

值	描述
IMPRESSIONS	按展示次数计费（最常见，使用频率超过 95%）
LINK_CLICKS	按链接点击计费
APP_INSTALLS	按应用安装计费
THRUPLAY	按视频观看计费
CLICKS	按任意点击计费
PAGE_LIKES	按主页赞计费
POST_ENGAGEMENT	按互动计费

完整列表（其他值）： LISTING_INTERACTION、NONE、OFFER_CLAIMS、PURCHASE

目标位置类型（最常见）

值	描述
WEBSITE	引导至网站 URL（最常见）
ON_AD	广告内目标位置（潜在客户表单、即时体验）
MESSENGER	Messenger 对话
WHATSAPP	WhatsApp 对话
INSTAGRAM_DIRECT	Instagram 私信
APP	移动应用
FACEBOOK	Facebook 目标位置
ON_POST	在帖子中
ON_VIDEO	在视频中
SHOP_AUTOMATIC	自动商店

完整列表（其他值）： APPLINKS_AUTOMATIC、FACEBOOK_LIVE、FACEBOOK_PAGE、IMAGINE、INSTAGRAM_LIVE、INSTAGRAM_PROFILE、INSTAGRAM_PROFILE_AND_FACEBOOK_PAGE、MESSAGING_INSTAGRAM_DIRECT_MESSENGER、MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP、MESSAGING_INSTAGRAM_DIRECT_WHATSAPP、MESSAGING_MESSENGER_WHATSAPP、ON_EVENT、ON_PAGE

推广目标

为优化转化所必需：

# For pixel conversions (OUTCOME_LEADS or OUTCOME_SALES)
'promoted_object': json.dumps({
    'pixel_id': 'YOUR_PIXEL_ID',
    'custom_event_type': 'LEAD'  # or PURCHASE, COMPLETE_REGISTRATION, etc.
})

# For lead gen forms (OUTCOME_LEADS with LEAD_GENERATION goal)
'promoted_object': json.dumps({
    'page_id': 'YOUR_PAGE_ID'
})

# For app installs
'promoted_object': json.dumps({
    'application_id': 'YOUR_APP_ID',
    'object_store_url': 'https://apps.apple.com/...'
})

custom_event_type 的取值

LEAD、PURCHASE、COMPLETE_REGISTRATION、ADD_TO_CART、ADD_TO_WISHLIST、INITIATE_CHECKOUT、ADD_PAYMENT_INFO、CONTACT、CUSTOMIZE_PRODUCT、DONATE、FIND_LOCATION、SCHEDULE、START_TRIAL、SUBMIT_APPLICATION、SUBSCRIBE、SEARCH、VIEW_CONTENT、OTHER

---

定向规范

完整结构

targeting = {
    # GEOGRAPHIC (required)
    'geo_locations': {
        'countries': ['US', 'CA', 'GB'],           # ISO country codes
        'country_groups': ['north_america', 'europe'],  # OR use region codes
        'regions': [{'key': '3847'}],               # State/province
        'cities': [{'key': '2430536', 'radius': 10, 'distance_unit': 'mile'}],
        'zips': [{'key': 'US:10001'}],
        'location_types': ['home', 'recent']        # home, recent, travel_in
    },

    # DEMOGRAPHICS
    'age_min': 25,                  # 13-65
    'age_max': 55,                  # 13-65
    'genders': [1],                 # 1=male, 2=female, omit or [0]=all
    'locales': [6],                 # Language codes (6=English)

    # INTEREST/BEHAVIOR TARGETING
    'flexible_spec': [
        {
            'interests': [{'id': '6003107902433', 'name': 'SaaS'}],
            'behaviors': [{'id': '6002714895372', 'name': 'Small business owners'}]
        }
    ],
    # flexible_spec logic:
    #   Within one object: fields are OR'd (interest1 OR behavior1)
    #   Multiple objects in array: OR'd together
    #   Use 'exclusions' for AND NOT logic

    'exclusions': {
        'interests': [{'id': '123', 'name': 'Excluded Interest'}]
    },

    # AUDIENCES
    'custom_audiences': [{'id': 'YOUR_AUDIENCE_ID'}],
    'excluded_custom_audiences': [{'id': 'YOUR_EXCLUDED_AUDIENCE_ID'}],

    # ADVANTAGE+ AUDIENCE
    'targeting_optimization': 'expansion_all',  # Enable Advantage+ expansion

    # PLATFORMS & PLACEMENTS (usually omit for Advantage+ Placements)
    'publisher_platforms': ['facebook', 'instagram', 'audience_network', 'messenger'],
    'device_platforms': ['mobile', 'desktop'],
    'facebook_positions': ['feed', 'story', 'facebook_reels', 'right_hand_column', 'search', 'marketplace', 'video_feeds', 'instream_video', 'profile_feed', 'biz_disco_feed', 'facebook_reels_overlay'],
    'instagram_positions': ['stream', 'story', 'reels', 'profile_reels', 'ig_search', 'explore', 'explore_home', 'profile_feed'],
    'messenger_positions': ['story', 'inbox'],
    'audience_network_positions': ['classic', 'rewarded_video'],

    # CONNECTIONS
    'connections': [{'id': 'YOUR_PAGE_ID'}],           # Connected to page
    'excluded_connections': [{'id': 'YOUR_PAGE_ID'}]   # Not connected to page
}

Advantage+ 受众（v23.0+）

'targeting_automation': {
    'advantage_audience': 1   # 1 = enabled, 0 = disabled
}

启用后，Meta 的 AI 会在你定义的定向范围之外进行扩展，以找到高意向用户。你仍需提供基础定向（地理位置、年龄等），但 Meta 可以超出这些范围。API v23.0+ 中默认启用。

地理位置定向规则

• 个人国家使用 countries：['US', 'CA', 'GB']
• 区域使用 country_groups：['north_america', 'europe']
• 当某个区域已覆盖相关国家时，不要列出 30 个以上的国家
• 地点之间绝不能重叠（例如，同时指定 US 和 New York City 会导致错误）
• 排除 Singapore，以避免填写监管合规字段

兴趣／行为搜索

# Search for targeting interests
GET /search?type=adinterest&q=KEYWORD&limit=10000&locale=en_US&access_token=TOKEN

# Response:
# { "data": [{ "id": "6003107902433", "name": "SaaS", "audience_size": 123456, "path": ["..."], "topic": "..." }] }

# Alternative: interest suggestions
GET /search?type=adinterestsuggestion&interest_list=["SaaS"]&access_token=TOKEN

API 会显示数千个 Ads Manager 自动补全中未显示的兴趣（自动补全中仅显示约 25 个）。

2026 年说明： 从 2025 年 6 月开始，许多详细定向兴趣已合并。使用 2025 年 10 月 8 日之前创建的兴趣的广告系列可能会停止投放。

---

广告创意架构

端点： POST /{account_id}/adcreatives

核心字段

字段	类型	描述
name	字符串	创意名称
object_story_spec	JSON 对象	主要创意内容容器
url_tags	字符串	URL 参数（仅可在创建时设置，之后无法更新）
instagram_user_id	字符串	IG 商业帐户 ID（在此处和 object_story_spec 中都要设置）
threads_user_id	字符串	Threads 个人资料 ID（在创意级别设置，不要放在 object_story_spec 中）
asset_feed_spec	JSON 对象	用于版位自定义或动态创意

object_story_spec——两种模式

模式 A：简单广告（link_data）

'object_story_spec': json.dumps({
    'page_id': 'YOUR_PAGE_ID',
    'instagram_user_id': 'YOUR_IG_USER_ID',
    'link_data': {
        'image_hash': 'HASH',
        'link': 'https://landing-page.com',
        'message': 'Body text',
        'name': 'Headline',
        'description': 'Description',
        'call_to_action': {
            'type': 'SIGN_UP',
            'value': {'link': 'https://landing-page.com'}
        }
    }
})

模式 B：版位自定义（asset_feed_spec）

'object_story_spec': json.dumps({
    'page_id': 'YOUR_PAGE_ID',
    'instagram_user_id': 'YOUR_IG_USER_ID'
    # NO link_data - all content goes in asset_feed_spec
})

重要： 使用 asset_feed_spec 时，object_story_spec 必须保持最简（仅包含 page_id + instagram_user_id）。包含 link_data 会导致错误。

link_data 字段

字段	类型	描述
link	字符串	目标 URL
message	字符串	广告正文
name	字符串	标题
description	字符串	标题下方的描述
caption	字符串	链接说明／域名显示
image_hash	字符串	已上传图片的哈希值
picture	字符串	图片 URL（image_hash 的替代项）
call_to_action	对象	CTA 按钮配置
child_attachments	数组	轮播卡片（2-10 张）
multi_share_optimized	布尔值	允许 Meta 展示效果最佳的卡片
multi_share_end_card	布尔值	在轮播中显示结束卡片

video_data 字段

'video_data': {
    'video_id': 'VIDEO_ID',           # From video upload (required)
    'image_url': 'THUMBNAIL_URL',      # From /{video_id}/thumbnails (required)
    'title': 'Video title',
    'message': 'Body text',
    'link_description': 'Description',
    'call_to_action': {
        'type': 'LEARN_MORE',
        'value': {'link': 'https://landing.com'}
    }
}

轮播 child_attachments

'child_attachments': [
    {
        'link': 'https://product1.com',
        'name': 'Card 1 Headline',
        'description': 'Card 1 description',
        'image_hash': 'IMAGE_HASH_1',
        'call_to_action': {
            'type': 'SHOP_NOW',
            'value': {'link': 'https://product1.com'}
        }
    },
    {
        'link': 'https://product2.com',
        'name': 'Card 2 Headline',
        'description': 'Card 2 description',
        'image_hash': 'IMAGE_HASH_2'
    }
    # 2-10 cards total, each card needs image_hash + link at minimum
]

CTA 类型（完整列表）

B2B 中最常用：

值	描述
SIGN_UP	注册
LEARN_MORE	了解更多
DOWNLOAD	下载
SUBSCRIBE	订阅
APPLY_NOW	立即申请
GET_QUOTE	获取报价
CONTACT_US	联系我们
BOOK_NOW	立即预订
REGISTER_NOW	立即注册
SHOP_NOW	立即购买
MESSAGE_PAGE	发送消息

按类别划分的完整列表：

商务：BUY_NOW、BUY_TICKETS、ORDER_NOW、SELL_NOW、GET_OFFER、ADD_TO_CART、PURCHASE_GIFT_CARDS、PAY_TO_ACCESS

信息：SEE_MENU、GET_SHOWTIMES、GET_DIRECTIONS

应用：INSTALL_APP、INSTALL_MOBILE_APP、USE_APP、USE_MOBILE_APP、GET_MOBILE_APP、PLAY_GAME、UPDATE_APP

互动：BOOK_TRAVEL、REQUEST_TIME、SEND_INVITES、REFER_FRIENDS、OPEN_MESSENGER_EXT、INSTAGRAM_MESSAGE、CALL、CALL_NOW、CALL_ME

媒体：WATCH_VIDEO、WATCH_MORE、LISTEN_MUSIC、LISTEN_NOW、GO_LIVE、RECORD_NOW

社交：LIKE_PAGE、VIEW_INSTAGRAM_PROFILE、INTERESTED、SAVE、SEND_TIP、DONATE、DONATE_NOW、EVENT_RSVP、VOTE_NOW

其他：OPEN_LINK、NO_BUTTON、BET_NOW、PRE_REGISTER、GET_EVENT_TICKETS、SEARCH_MORE

url_tags

• 仅在创建时设置到广告素材上——无法更新，必须重新创建广告素材
• 标准格式：utm_source=meta&utm_medium=paid-social&utm_campaign={{adset.name}}&utm_content={{ad.name}}
• 动态参数：{{campaign.name}}、{{campaign.id}}、{{adset.name}}、{{adset.id}}、{{ad.name}}、{{ad.id}}、{{placement}}、{{site_source_name}}

---

广告架构

端点： POST /{account_id}/ads

字段	类型	必填	描述
name	string	是	广告名称
adset_id	string	是	父广告组 ID
creative	JSON object	是	{"creative_id": "CREATIVE_ID"}
status	enum	是	PAUSED（绝不可设为 ACTIVE）
tracking_specs	JSON array	否	额外的转化跟踪

---

自定义受众架构

端点： POST /{account_id}/customaudiences

客户名单上传

# Step 1: Create audience
'name': 'My Customer List',
'subtype': 'CUSTOM',
'customer_file_source': 'USER_PROVIDED_ONLY'

# Step 2: Add users via /{audience_id}/users
'schema': ['EMAIL', 'FN', 'LN'],   # or 'PHONE', 'MOBILE_ADVERTISER_ID', 'UID'
'data': [
    ['sha256_hashed_email', 'sha256_hashed_firstname', 'sha256_hashed_lastname'],
    # ... up to 10,000 per batch
]

发送前，所有 PII 字段都必须经过 SHA-256 哈希处理。规范化：转为小写、去除空白字符，电话号码使用 E.164 格式。

网站自定义受众

'name': 'Website Visitors - Last 30 Days',
'subtype': 'WEBSITE',
'rule': json.dumps({
    'inclusions': {
        'operator': 'or',
        'rules': [{'event_sources': [{'id': 'YOUR_PIXEL_ID', 'type': 'pixel'}], 'retention_seconds': 2592000}]
    }
})

类似受众

'name': '1% Lookalike - US - Customer List',
'subtype': 'LOOKALIKE',
'origin_audience_id': 'SOURCE_AUDIENCE_ID',   # min 100 members, recommended 1000-5000
'lookalike_spec': json.dumps({
    'ratio': 0.01,          # 1% similarity (0.01 to 0.20)
    'country': 'US',        # Single country per lookalike
    'starting_ratio': 0.00  # Optional: for tiered lookalikes (e.g., 1-2% tier)
})

**分层模式：**先创建 0-1%（ratio=0.01），然后创建 1-2%（ratio=0.02，starting_ratio=0.01），再创建 2-3%（ratio=0.03，starting_ratio=0.02）。

**2026 年说明：**创建新的类似受众时，lookalike_spec 是必需项（自 2026 年 1 月 6 日起）。

---

覆盖人数估算

端点： GET /{account_id}/reachestimate

params = {
    'access_token': token,
    'currency': 'USD',
    'optimize_for': 'OFFSITE_CONVERSIONS',
    'targeting_spec': json.dumps({
        'geo_locations': {'countries': ['US']},
        'age_min': 25,
        'age_max': 55
    })
}

返回估算受众规模范围、估算每日结果和出价估算值。

---

成效分析 / 报告

端点： GET /{object_id}/insights（适用于账户、广告系列、广告组或广告级别）

核心参数

参数	类型	描述
fields	string	以逗号分隔的指标
date_preset	enum	预定义日期范围
time_range	JSON	自定义日期范围 {"since":"2026-01-01","until":"2026-01-31"}
level	enum	campaign、adset、ad（细分级别）
breakdowns	string	以逗号分隔的投放细分项
action_breakdowns	string	以逗号分隔的操作细分项
time_increment	int or string	1-90（天）、"monthly"、"all_days"
limit	int	每页结果数（默认 25）
filtering	JSON array	筛选条件

日期预设

today、yesterday、last_3d、last_7d、last_14d、last_28d、last_30d、last_90d、this_week_mon_today、this_week_sun_today、last_week_mon_sun、last_week_sun_sat、this_month、last_month、this_quarter、last_quarter、this_year、last_year、maximum、lifetime

常用指标

spend、impressions、clicks、reach、frequency、ctr、cpc、cpm、actions、cost_per_action_type、action_values、conversions、cost_per_conversion、conversion_values、purchase_roas

投放细分维度

细分维度	说明
age	年龄范围
gender	性别
country	国家/地区
region	地区/州
dma	DMA（仅限美国）
publisher_platform	Facebook、Instagram 等
platform_position	Feed、快拍、Reels 等
device_platform	移动设备、桌面设备
impression_device	设备类型
frequency_value	频次分布
hourly_stats_aggregated_by_advertiser_time_zone	一天中的小时（广告主时区）
hourly_stats_aggregated_by_audience_time_zone	一天中的小时（受众时区）
product_id	商品目录 ID

动态创意细分维度： ad_format_asset、body_asset、call_to_action_asset、description_asset、image_asset、link_url_asset、title_asset、video_asset

重要： 同一请求中不能同时组合投放细分维度和 action_breakdowns。请分别请求。

操作细分维度

细分维度	说明
action_type	操作类型（潜在客户、购买等）
action_device	发生操作的设备
action_destination	操作跳转到的位置

action_type 值

最常用：

action_type	说明
lead	在平台内提交潜在客户表单
link_click	点击链接
landing_page_view	查看落地页
post_engagement	帖子互动
video_view	视频观看
page_engagement	页面互动
onsite_conversion.lead_grouped	平台内归类的潜在客户事件
offsite_conversion.fb_pixel_lead	Pixel 潜在客户事件
offsite_conversion.fb_pixel_purchase	Pixel 购买事件
offsite_conversion.fb_pixel_add_to_cart	Pixel 加入购物车
offsite_conversion.fb_pixel_initiate_checkout	Pixel 发起结账
offsite_conversion.fb_pixel_complete_registration	Pixel 注册
offsite_conversion.fb_pixel_view_content	Pixel 查看内容
offsite_conversion.fb_pixel_custom	Pixel 自定义转化
omni_purchase	跨渠道购买
omni_add_to_cart	跨渠道加入购物车

从操作中提取转化

actions = row.get('actions', [])
leads = sum(int(a['value']) for a in actions if a['action_type'] == 'lead')
pixel_leads = sum(int(a['value']) for a in actions if a['action_type'] == 'offsite_conversion.fb_pixel_lead')

异步报告（大型数据集）

对于较大的日期范围或复杂的细分维度：

# Request async report
params['async'] = True
r = requests.get(url, params=params)
report_id = r.json()['report_run_id']

# Poll for completion
status_url = f'https://graph.facebook.com/v22.0/{report_id}'
r = requests.get(status_url, params={'access_token': token})
# Check async_status: "Job Completed", "Job Running", etc.

# Download results
results_url = f'https://graph.facebook.com/v22.0/{report_id}/insights'
r = requests.get(results_url, params={'access_token': token})

数据保留期限（2026）

• 唯一计数类字段：保留 13 个月的历史数据
• 频次细分数据：6 个月
• 按小时细分的数据：13 个月
• 超过 100 个指标已弃用（包括 unique_actions）

---

归因设置（2026）

attribution_spec

'attribution_spec': json.dumps([
    {'event_type': 'CLICK_THROUGH', 'window_days': 7},
    {'event_type': 'VIEW_THROUGH', 'window_days': 1}
])

可用窗口期（2026 年 1 月 12 日之后）

点击归因	浏览归因
1 天	1 天
7 天（默认）	7 天 已移除
	28 天 已移除

默认设置：7 天点击 + 1 天浏览（7d_click / 1d_view）。

影响： 7 天和 28 天浏览归因窗口期已于 2026 年 1 月 12 日移除。使用这些窗口期的历史报告将不再返回数据。

---

Conversions API（CAPI）- 服务端事件

端点： POST /{pixel_id}/events

事件结构

{
    'data': [
        {
            'event_name': 'Lead',               # Standard event name
            'event_time': 1709568234,            # Unix timestamp
            'event_id': 'unique-event-12345',    # For deduplication with pixel
            'action_source': 'website',          # website, app, offline, etc.
            'event_source_url': 'https://site.com/page',
            'user_data': {
                'em': ['sha256_hashed_email'],   # MUST be hashed
                'ph': ['sha256_hashed_phone'],   # MUST be hashed, E.164 format
                'fn': ['sha256_hashed_first'],   # MUST be hashed, lowercase
                'ln': ['sha256_hashed_last'],    # MUST be hashed, lowercase
                'fbp': 'fb.1.123.456',           # NOT hashed (browser cookie)
                'fbc': 'fb.1.123.456',           # NOT hashed (click cookie)
                'external_id': ['sha256_hashed_id'],
                'client_ip_address': '1.2.3.4',
                'client_user_agent': 'Mozilla/5.0...'
            },
            'custom_data': {
                'value': 99.99,                  # Required for Purchase
                'currency': 'USD',               # Required for Purchase
                'content_ids': ['product123'],
                'content_type': 'product',
                'order_id': 'order-456'
            }
        }
    ],
    'access_token': token
}

标准事件名称

Purchase、Lead、ViewContent、AddToCart、InitiateCheckout、CompleteRegistration、AddPaymentInfo、AddToWishlist、Contact、FindLocation、Schedule、Search、StartTrial、SubmitApplication、Subscribe、CustomizeProduct、Donate

去重

• Pixel 和 CAPI 都必须发送相同的 event_name + event_id
• Meta 会自动对匹配的事件去重
• 不进行去重时，转化次数会被重复计算
• 在服务端生成 event_id，并将其传给 Pixel 和 CAPI

user_data 哈希规则

字段	是否哈希？	备注
em（电子邮件）	SHA-256	先规范化为小写
ph（电话）	SHA-256	使用 E.164 格式，不含空格或连字符
fn（名字）	SHA-256	小写
ln（姓氏）	SHA-256	小写
external_id	SHA-256	您的客户 ID
fbp	否	浏览器 Cookie，发送原始值
fbc	否	点击 Cookie，发送原始值
client_ip_address	否	发送原始值
client_user_agent	否	发送原始值

**重要：**对 fbp 或 fbc 进行哈希会导致匹配完全失效。

---

图片上传

端点：POST /{account_id}/adimages

要求

• 格式：JPG 或 PNG
• 最大大小：30MB
• 建议：至少 1080x1080px
• 宽高比：1:1（动态消息）、4:5（动态消息）、9:16（快拍/Reels）

响应

{
  "images": {
    "filename.jpg": {
      "hash": "a1b2c3d4e5f6...",
      "url": "https://scontent.xx.fbcdn.net/...",
      "height": 1080,
      "width": 1080
    }
  }
}

---

视频上传

端点：POST /{account_id}/advideos

要求

• 格式：MP4、MOV（建议使用 H.264 编码）
• 最大大小：4GB
• 动态消息：1s 至 240 分钟，宽高比为 4:5 或 1:1
• 快拍/Reels：1-60s（建议 15s），宽高比为 9:16
• 创建广告时必须提供缩略图——通过 GET /{video_id}/thumbnails 获取

分块上传（适用于 >100MB 的文件）

分为三个阶段：

1. upload_phase=start + file_size -> 返回 upload_session_id
2. upload_phase=transfer + upload_session_id + start_offset + video_file_chunk（循环执行）
3. upload_phase=finish + upload_session_id + title -> 返回视频 ID

---

分页

data = r.json()
results = data.get('data', [])

while 'paging' in data and 'next' in data['paging']:
    r = requests.get(data['paging']['next'])
    data = r.json()
    results.extend(data.get('data', []))

---

CRUD 操作

创建

r = requests.post(f'https://graph.facebook.com/v22.0/{parent_id}/{edge}', data={...})
# edge: campaigns, adsets, ads, adcreatives, adimages, advideos, customaudiences

读取

r = requests.get(f'https://graph.facebook.com/v22.0/{object_id}', params={
    'fields': 'field1,field2,...',
    'access_token': token
})

更新

r = requests.post(f'https://graph.facebook.com/v22.0/{object_id}', data={
    'name': 'New Name',
    'status': 'PAUSED',
    'access_token': token
})

删除

r = requests.delete(f'https://graph.facebook.com/v22.0/{object_id}', params={
    'access_token': token
})

---

关键注意事项与规则

1. 始终使用 Python，切勿使用 curl——令牌包含的字符可能会在 shell 插值时被错误处理
2. 始终通过 dotenv 从 .env 加载令牌——切勿将令牌粘贴到命令中
3. 预算以美分计——5000 = $50.00
4. is_adset_budget_sharing_enabled 是字符串——"true" / "false"，不是布尔值
5. 要更新 URL、文案或任何创意内容——向广告（而不是创意）发送 POST 请求，并在内联 creative JSON 中提供包含完整规范及变更的内容。也可以用这种方式更改 url_tags。
6. Instagram 账户有两个设置位置——顶层的 instagram_user_id 和 object_story_spec 内部都要设置
7. 使用 asset_feed_spec 时，object_story_spec 应保持精简——仅包含 page_id + instagram_user_id，不包含 link_data
8. 不同版位使用不同图片时设置 optimization_type: PLACEMENT；动态创意则使用 REGULAR
9. REGULAR 将每个广告组限制为 1 个广告——需要多个广告时使用 PLACEMENT
10. 必须提供视频缩略图——上传后从 /{video_id}/thumbnails 获取
11. 单次上传无法处理 >100MB 的文件——大视频始终使用分块上传
12. 定向时排除新加坡，以避免监管合规字段要求
13. 自定义受众服务条款——错误 1359208 表示需要在 Ads Manager UI 中重新接受条款（API 无法检测此情况）
14. 空的 data: [] 表示该时段内没有活动，不是错误
15. 同一个 insights 请求中不能同时使用投放和操作细分
16. 广告文案格式——段落之间始终使用 \n\n，列表内使用 \n
17. Threads 个人主页身份——在创意级别设置 threads_user_id（不要放在 object_story_spec 内）。要查找 Threads 个人主页 ID，请检查一个现有的有效创意：GET /{creative_id}?fields=threads_user_id。Threads 个人主页关联的是 Instagram 账户，而不是 Facebook 公共主页本身。