开发自己的广告投放系统

01 / 先分清三种使用方式

三种方式都能访问已授权资产，区别是谁发起任务、谁安排执行、操作入口在哪里。它们不是三个不同的权限等级。

本页讲第三种：先用 Python 接通查询，再把它放进自己的业务后台。即使没有 AI 模型，也可以开发报表、广告管理和规则执行功能。

02 / 第一版系统可以从这几个模块开始

1. 先接通查询。完成下面的只读示例，核对账户 ID 与报表返回。
2. 再做自己的报表页。由后端请求接口，前端展示数据；Token 保存在服务端私密配置中。
3. 再接入单次修改。增加审批、账户范围和执行后回读，先验证一个明确的操作。
4. 最后加入规则或 AI。规则和模型产生建议，经过同一套权限与执行流程后操作资产。

前端页面不应直接携带服务 Token 请求接口。由你的后端验证登录用户能操作哪些资产，再调用对应接口。

03 / 选择一种接口路线，再配置对应凭证

先向开通团队确认拿到哪种凭证。下面三类凭证的签发方、用途和请求域名不同。

Graph 两条路线使用 Facebook 原生资产 ID。Meta System User 路线需要把广告户和投放主页分别分配给生成 Token 的同一个 System User，再核对 App、Token scopes 和具体操作权限。只有 Token 字符串或只授权广告户，还不足以支持主页相关广告操作。

详细的域名替换、BM 授权和两类资产验证见凭证与接口参考。Meta 原生 Token 不填入 ActionKey REST 的 Bearer 配置，内部中转 Token 不发往 graph.facebook.com。

GET https://baiz.ai/api/mcp/ad-accounts?per_page=20
Authorization: Bearer {ActionKey服务Token}
Accept: application/json

所有方法、路径和字段以ActionKey 公开接口说明 ↗及你的实际开通范围为准。本教程根据该说明编写，不代表每个 Token 都具备全部操作权限。

04 / 运行一个可以改造成后台模块的 Python 示例

准备 Python 3.9 或更新版本。示例使用标准库，无需安装依赖；只提供账户查询、计划列表和效果查询，不包含创建、暂停或预算修改。

下载 Python 客户端 · 下载示意数据。将两个文件放在同一文件夹中，再打开该文件夹的终端。

先跑示意数据，不需要 Token

python3 actionkey_client.py --demo accounts
python3 actionkey_client.py --demo campaigns --ad-account-id 7
python3 actionkey_client.py --demo report --campaign-id 42

输出中 demo: true 表示示意数据。示例里的账户内部 ID 7、计划内部 ID 42 和 Facebook ID 都是占位值，不对应你的资产。

用实际服务 Token 验证账户查询

python3 actionkey_client.py accounts --per-page 20

程序会提示输入 ActionKey 服务 Token，输入不回显。已经由运行环境设置 ACTIONKEY_TOKEN 时，程序直接读取它；这个变量名只是本示例的本地约定。只在你的终端或后端私密配置中设置凭证。

核对返回账户的 id、ad_account_id、currency 和 timezone_name。示例读取本次返回的一页账户，不会假设已经获取全部账户。

按广告户内部 ID 找到计划

从上一步返回的账户中读取 id，将下面的 7 替换成这个内部 ID。这里不用 Facebook 广告户 ID。

python3 actionkey_client.py campaigns --ad-account-id 7 --per-page 20

程序调用 GET /campaigns 并传入 ad_account_id 和 per_page。在返回的 campaigns 列表中核对计划名称、状态及 id；这个 id 就是下一步的计划内部 ID。本次只读取一页计划；公开说明未列出该端点的 page 参数，示例不会自行加入它。

查询指定计划的广告效果

从上一步选定一个计划，将下面的 42 替换成它的 ActionKey 内部 id。不要把 Facebook Campaign ID 填入命令。

python3 actionkey_client.py report --campaign-id 42 --page 1 --per-page 50 > report.json

程序调用 GET /campaigns/{id}/ads，输出 campaign、metrics、分页和 errors。读取报告时同时检查程序退出码：0 为本次查询成功，1 为请求或解析失败，2 表示接口返回了部分资产错误。不能仅因生成了文件就认为报表完整。

读取多页广告时，先确认 metrics 是全计划汇总还是单页汇总；不要直接叠加每一页的汇总指标，以免把重复的汇总计算多次。示例只输出本次响应，不跨页累加。

账户与计划列表解析兼容直接数组和含 data 数组的对象；公开说明未固定这两种列表的包装结构，若实际结构不同会明确报错。接入自己的数据库和页面时，先依据真实响应确定字段结构、分页方式与缺失值，不把缺失指标填成零。

把客户端放进你的后端

import os
from actionkey_client import ActionKeyClient, format_report

client = ActionKeyClient(os.environ["ACTIONKEY_TOKEN"])
data = client.get("/campaigns/42/ads", {"page": 1, "per_page": 50})
report, partial_failure = format_report(data)
# 将 42 替换为已核对的计划内部 ID。
# 在你的后端校验登录用户与计划的访问权限，再返回或保存报告。

接口客户端只是系统的一部分。将查询结果写入你选用的数据库，记录查询时间与范围，再由自己的页面读取；加入调度前先确认一次真实查询与展示完整跑通。

05 / 保存资产映射，避免把两个 ID 混用

你的资产目录至少保存“对象类型、ActionKey 内部 ID、Facebook 原生 ID、所属广告户、名称、币种、时区、最后核对时间”。ID 可作为字符串保存，调用要求整数的 REST 参数时再检查转换，避免大整数在前端丢失精度。

每次操作前用类型和所属账户重新核对映射；不要仅凭同名对象选中资产。接口里名称含 facebook 的参数也可能要求内部 ID，按该端点的字段说明判断。

06 / 把一次修改做成可确认、可核对的操作

1. 读取现状。核对目标内部 ID、关联广告户、当前状态或预算、币种和本次允许操作范围。
2. 生成待确认方案。保存目标对象、操作类型、调整前后值、影响范围和有效期；让操作者看到具体变化。
3. 保存确认。记录确认人、时间和方案版本。参数变化或现状变化时让方案重新确认。
4. 校验并执行一次。后端再次检查用户权限、账户白名单、金额上限和确认状态；同一账户修改放入串行队列。
5. 回读并记录。区分“接口已接受”“异步处理中”“回读已确认”和“结果待核对”，保存对应证据。

预算调整：先明确账户级影响

公开接口 POST /campaigns/{id}/budget 用计划内部 ID 定位，但 adjust_budget 实际控制关联广告账户级别预算，可能影响同一广告户中的其他投放。amount 的单位是美元 USD；日预算字段为 limit_daily_amount，总预算字段为 limit_amount。

{
  "action": "set",
  "amount": 30,
  "budget_field": "limit_daily_amount"
}

上面的 30 表示目标金额 30 USD，不是加 30，也不是 30 分。正式接入前核对关联账户实际预算、账户币种与 USD 换算 / 同步规则，并在方案中展示对同户其他投放的影响。

失败与超时怎么处理

查询可以按明确的重试次数与退避规则恢复。修改、创建或发布超时可能已经被服务端接受，先查询对象与操作结果，不要直接再次提交。公开说明未承诺通用幂等键；不要自行添加一个请求头就认为不会重复执行。你自己的操作记录与账户锁用于防止本系统重复提交，不能替代服务端幂等保证。

07 / 创建广告，先准备引用对象再发布

ActionKey 的创建流程使用已保存对象的内部 ID。先把每类资源准备好，再组装广告计划；所有必填字段见公开接口说明。

创建计划时，copywriting_ids、targeting_ids、file_ids、offer_ids、facebook_page_id 和 ad_account_ids 引用 ActionKey 内部资源。确认 start_time / end_time 的时间解释、账户时区以及具体预算字段单位后再提交。

不要用创建接口当作前端“保存草稿”按钮；先将方案存在自己的数据库。公开 /publish 只支持草稿（0）或发布失败（10）状态，重试前需核对实际对象与失败原因。删除计划会先停止 Facebook 广告，再执行软删除，同样需要明确确认。

08 / 部署后，再加入定时查询和规则执行

Python 示例是一次查询程序，终端结束就停止。持续运行需要将客户端部署到自己的后端，通过所选平台的任务调度器安排周期，并配置运行记录与通知。

• 凭证与权限：凭证放在后端私密配置；区分团队与操作者的资产范围，记录授权变更，避免在访问日志中写入 Token。
• 任务范围：明确账户、查询周期、时区与统计口径；账户或报表部分失败时标记缺失，不能把缺失花费当成零。
• 执行规则：先只读巡检和建议；需要自动修改时保存具体预授权的账户、动作、金额上限、有效期和停止入口。
• 任务互斥：避免定时任务重叠；同一账户执行修改时加锁，接口限流时按实际限制退避。
• 运行记录：记录操作者 / 任务、对象 ID、方案版本、确认、执行时间、接口结果、回读结果与待核对事项。

加入 AI 时，让模型输出结构化建议，再由后端校验并交给同一执行队列。模型生成的理由不替代资产权限、审批记录或实际回读。若希望 Agent 自己选择并编排工具，转到AI Agent 调用教程。

固定服务费 ¥5,000 / 月，不限制请求数。广告消耗、模型和运行环境费用另行承担，Meta 与相关接口自身的限流仍然适用。接口调用仍受 Facebook 权限、审核和账户风控约束。

常见问题

我需要先开发 AI Agent 吗？

不需要。先开发自己的后端和规则系统就能调用 REST / Graph。Agent 是由模型选择工具、编排步骤的另一种入口；后续可以把你的业务函数开放给 Agent 使用。

ChatGPT Plugin 算自己的系统吗？

Plugin 可以封装自己的后端工具，但用户主要在聊天中发起任务。本教程侧重独立投放后台与服务器任务；如果想从 ChatGPT 发起调用，另看自助创建 Plugin 教程。

已有 Graph 代码能复用吗？

可以按凭证路线适配。尤里改内部中转 access_token 要同时改用 facebook-graph.baiz.ai；Meta System User Token 使用 graph.facebook.com，广告户与主页分别授权给同一系统用户。SDK 地址配置和支持端点需按实际版本验证。

示例已经完成自动投放了吗？

没有。示例只查询账户、计划和效果，帮助你完成第一条接口链路。广告创建、审批、实际预算回读、任务调度和通知需要按本页后续步骤在自己的系统中实现。