📸 Instagram 广告 API

Instagram 广告 API 让您以编程方式在 Instagram 上创建和管理广告。广告通过 Facebook 广告系列结构投放，利用 Instagram 版位进行针对性投放。

广告系列架构

Instagram 广告使用与 Facebook 广告相同的三层结构：广告系列 → 广告组 → 广告（含创意）。区别在于广告组定位中指定 Instagram 版位。

支持的版位

版位	展示位置	支持的目标
动态 (Stream)	Instagram 首页信息流	品牌知名度、覆盖人数、流量、互动、应用安装、视频观看、转化
快拍 (Story)	Instagram 快拍	品牌知名度、覆盖人数、流量、互动、转化
探索 (Explore)	Instagram 探索页	品牌知名度、覆盖人数、流量
Reels	Instagram Reels	品牌知名度、覆盖人数、流量
搜索结果 (Search)	Instagram 搜索结果	覆盖人数、流量
个人主页 (Profile)	Instagram 个人主页	覆盖人数、流量

入门指南

在 Instagram 上投放广告的 5 个步骤：

获取 Instagram 账户 ID — 通过商务管理平台或图谱 API 获取
创建广告系列 — 使用 Marketing API 创建 Campaign，选择目标
创建广告组 — 指定 Instagram 版位定位
创建广告创意 — 使用 Instagram 素材格式
排期并发布 — 设置预算和时间表

API 请求示例（创建广告组，指定 Instagram 版位）：

curl -X POST \
  -F 'name=My IG Ad Set' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'daily_budget=1000' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'optimization_goal=REACH' \
  -F 'targeting={
       "instagram_positions": ["stream", "story"],
       "geo_locations": {"countries": ["US"]},
       "publisher_platforms": ["instagram"]
     }' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets

素材要求

素材类型	规格
图片最小宽度	600px
图片宽高比	1:1 / 4:5 / 1.91:1
视频时长	3 至 60 秒
视频最大文件	2.3GB
文字上限（仅 IG）	2,200 字符

快拍广告要求

全屏竖屏 (9:16) 素材
视频最长 15 秒
建议分辨率：1080×1920px

裁剪行为

发布广告时，Facebook 自动裁剪素材以适配不同版位。若提供 100x100 裁剪参数，系统将使用指定裁剪而非自动裁剪。

数据和行动号召要求

Instagram 广告支持以下行动号召类型：SHOP_NOW、LEARN_MORE、INSTALL、SIGN_UP、CONTACT_US、GET_DIRECTIONS、BOOK_NOW、BUY_NOW 等。

每个广告格式有特定的数据字段要求，包括目标 URL、应用深层链接、公共主页信息等。

创意指南

轮播广告：最多 10 张图片/视频，每张图片建议 600×600px
视频广告：支持 Feed、Story、Reels 版位
合创广告 (Branded Content): 创建品牌内容广告，指定合作伙伴
动态广告 (Dynamic Ads): 使用目录自动展示商品

🌐 转化 API 网关（CAPI Gateway）

CAPI Gateway 是一种自托管解决方案，可在您的云环境中快速设置转化 API 实例，无需专门的开发资源。

架构

Pixel 像素代码 → CAPI Gateway → 转化 API 端点

Gateway 在您的云中运行，自动将浏览器事件转发到 Meta，并自动生成 event_id 实现去重。

关键特性

支持 AWS 和 GCP 部署
自动事件去重（无需手动设置 event_id）
多 Pixel、多网域支持
每月费用约 $40-$300+（取决于用量）

部署方式

通过 Events Manager 中的"转化 API 网关"选项一键部署 AWS CloudFormation 模板，或在 GCP 上设置。需提供 AWS 账户 ID 和区域等信息。

设置指南

在 Events Manager 中创建 Gateway 实例
选择云平台（AWS/GCP）
配置 CloudFormation 模板（AWS）
设置自定义域名（可选，需 ACM/Cloudflare）
将 Pixel 指向 Gateway 端点
验证事件接收

Control Plane API

用于以编程方式管理 Gateway 实例的 GraphQL API。支持：

操作	描述
账户管理	创建、读取、更新、删除、列出账户
用户管理	管理 Gateway 用户权限
Pixel 管理	关联/取消关联 Pixel
数据路由	配置账户数据路由
事件指标	查看账户事件指标

身份验证支持 MBE（Managed Business Extension）或手动令牌。令牌有效期 10 小时。

🤖 Ads CLI（广告 AI 连接器）

Ads CLI 是一个命令行工具，用于以编程方式管理 Meta 广告。支持完整的广告生命周期管理。

功能

功能	命令
广告系列管理	`meta ads campaign list/create/get/update`
广告组管理	`meta ads adset list/create/get/update`
广告管理	`meta ads ad list/create/get/update`
创意管理	`meta ads creative list/create`
成效分析	`meta ads insights get --fields spend,impressions`
目录管理	`meta ads catalog list`
Pixel 管理	`meta ads pixel list`

安装与设置

# 安装
pip install meta-ads

# 设置系统用户令牌
export META_ADS_ACCESS_TOKEN=<your-token>

# 第一个命令
meta ads campaign list

# JSON 输出
meta ads campaign list --format json

# 无交互模式（CI/CD）
meta ads campaign create --name "My Campaign" --objective OUTCOME_TRAFFIC --no-input

要求：Python 3.12+，系统用户令牌需包含 ads_management、business_management、pages_show_list 等权限。

← 转化 API 📚 返回目录 →