凭证与接口参考

01 / 先准备账户、权限和运行环境

查询广告数据需要目标广告账户的读取权限；创建广告时，还要确认投放主页及该广告所需的其他资产权限。无论用 AI 助手还是自研系统，凭证都要与接入路线匹配。

1. 明确业务对象。列出要操作的广告户、主页，以及查询、创建、预算或状态调整需求。涉及像素、Instagram 身份等资产时，一并确认所需授权。
2. 确认凭证来源。开通时说明要使用 ActionKey REST / MCP、Graph 中转接口，还是 BM 内的 Meta System User Token；按下面对应路线配置。
3. 准备受控环境。将凭证保存在服务端或 Agent 运行环境的凭证存储中，再接入客户端或业务系统。

先选择使用方式：聊天调用、AI Agent 调用或开发自己的系统。MCP、REST 和 Graph 是调用通道，选择通道不会自动赋予额外权限或安排任务。

02 / 两类 Graph Token，走两条接入路线

不要只看凭证都叫 access_token。先确认是谁签发的，再选择请求地址和授权步骤。

03 / 路线 A：尤里改内部中转 Token

适合通过 ActionKey Graph 代理复用已有投放系统的调用方式。获取内部中转 access_token 后，需要同时修改凭证和请求域名。

配置 Graph 代理地址

GET https://facebook-graph.baiz.ai/{API版本}/act_{Facebook广告账户ID}/campaigns

参数：
  access_token = 尤里改内部中转Token
  fields       = id,name,status
  limit        = 25

1. 向尤里改团队确认该凭证是内部中转 Token，以及允许访问的广告户和主页。
2. 将 SDK 或 HTTP 客户端的 Graph 基础域名改为 facebook-graph.baiz.ai，再替换 access_token。
3. 检查实际发出的请求域名，先运行只读验证请求，再适配业务操作。

不同 SDK 的基础地址配置方式不相同。接口路径、API 版本、批量请求和所需字段按实际实现逐项验证，改动量取决于 SDK 版本及你的业务代码。

04 / 路线 B：BM 内生成 System User Token

如果使用 BM 内、由尤里改授权的 App 生成的 Meta System User Token，请连接 graph.facebook.com。这个 Token 代表对应 System User 调用 Meta API，权限来自 App、Token 的 API scopes 和 System User 的资产权限。

在 BM 中逐项完成授权

1. 确认 BM 与授权 App。先让尤里改团队确认可用的 App 及其授权状态。不要在生成 Token 时随意改选其他 App；如果 App 不可选或所需权限不可用，先处理开通配置。
2. 选中对应 System User。在 BM / Meta Business Suite 的业务设置中，进入“用户 → 系统用户（System Users）”，选择需要代表你的程序调用 API 的系统用户。
3. 分配广告账户。在“分配资产 / 添加资产”中选中目标广告户，授予实际需要的广告任务权限。只读查询与创建、修改广告需要的资产任务不同。
4. 单独分配主页。继续选中广告使用的 Facebook 主页，授予对应主页任务权限。只给 System User 分配广告户，不会自动获得该主页的权限；多个主页需要分别确认。
5. 使用授权 App 生成 Token。选择尤里改已授权的 App，按实际 API 操作选择所需 scopes，再生成并保存 System User Token。Token 期限与状态按生成界面及实际授权确认。
6. 检查已分配资产。回到该 System User 的资产列表，核对广告户和主页的 ID、任务权限，并分别运行只读验证。

API scopes 与资产权限是两层检查

所需 scopes 以具体端点为准；生成界面中的选项、App 访问级别和资产任务都需要符合当前业务。不要为了排障默认授予所有管理权限，也不要把 ads_management 理解为自动授权所有主页。

官方参考：Meta 官方 Marketing API 接入与广告权限说明 ↗、Meta System Users 概览 ↗、Meta API 权限说明 ↗。业务设置中的菜单名称可能随界面更新变化，以当前 BM 中的实际选项为准。

05 / 使用 ActionKey MCP 或封装 REST API

如果开通的是 ActionKey MCP / REST 服务，使用 ActionKey 提供的服务凭证与服务地址。这里的认证配置独立于上面的 Meta 原生 System User Token 路线。

连接 AI 助手：按照Claude、Codex、Gemini、Grok 接入指南配置 MCP 或工具调用。

开发自己的系统：可以使用 ActionKey REST API。每个操作的方法、路径、参数与返回字段见完整接口说明 ↗。

https://baiz.ai/api/mcp

认证请求头为 Authorization: Bearer ActionKey 服务Token。先按公开说明及开通范围核对操作；不要把 Meta 原生 System User Token 当成这个服务 Token 使用。

06 / 按所选路线验证只读请求

先确认地址、凭证类型与目标对象是否匹配，再检查返回内容。下面的示例仅查询数据，不会创建广告或修改预算。

A. 验证内部中转 Token

在 macOS / Linux 的同一终端中设置 YURI_RELAY_TOKEN 为内部中转凭证、META_API_VERSION 为已确认支持的版本（包含 v 前缀）、META_AD_ACCOUNT_ID 为不带 act_ 的 Facebook 广告账户 ID。下面请求会自动加上 act_。

set_yuri_relay_context() {
  printf '请输入尤里改内部中转 Token：'
  IFS= read -r -s YURI_RELAY_TOKEN
  printf '\n请输入已确认的 API 版本（含 v 前缀）：'
  IFS= read -r META_API_VERSION
  printf '请输入 Facebook 广告户 ID（不带 act_）：'
  IFS= read -r META_AD_ACCOUNT_ID
  export YURI_RELAY_TOKEN META_API_VERSION META_AD_ACCOUNT_ID
}
set_yuri_relay_context

curl --fail-with-body --silent --show-error --get \
  "https://facebook-graph.baiz.ai/${META_API_VERSION}/act_${META_AD_ACCOUNT_ID}" \
  --data-urlencode "access_token=$YURI_RELAY_TOKEN" \
  --data-urlencode "fields=id,name,account_status"

检查 HTTP 状态、错误内容及返回的账户 ID。若请求仍发往 graph.facebook.com，先修正域名，再排查代理凭证与开通范围。

B. 验证 Meta System User Token

在 macOS / Linux 的同一终端中设置 META_SYSTEM_USER_TOKEN 为 Meta 原生系统用户凭证、META_API_VERSION 为该 App 使用的 API 版本、META_AD_ACCOUNT_ID 为不带 act_ 的广告户 ID、META_PAGE_ID 为 Facebook 主页 ID。使用下面的独立设置示例，避免与 ActionKey 服务凭证混用。

set_meta_system_user_context() {
  printf '请输入 Meta System User Token：'
  IFS= read -r -s META_SYSTEM_USER_TOKEN
  printf '\n请输入该 App 使用的 API 版本（含 v 前缀）：'
  IFS= read -r META_API_VERSION
  printf '请输入 Facebook 广告户 ID（不带 act_）：'
  IFS= read -r META_AD_ACCOUNT_ID
  printf '请输入 Facebook 主页 ID：'
  IFS= read -r META_PAGE_ID
  export META_SYSTEM_USER_TOKEN META_API_VERSION META_AD_ACCOUNT_ID META_PAGE_ID
}
set_meta_system_user_context

curl --fail-with-body --silent --show-error --get \
  "https://graph.facebook.com/${META_API_VERSION}/act_${META_AD_ACCOUNT_ID}" \
  -H "Authorization: Bearer $META_SYSTEM_USER_TOKEN" \
  --data-urlencode "fields=id,name,account_status"

curl --fail-with-body --silent --show-error --get \
  "https://graph.facebook.com/${META_API_VERSION}/${META_PAGE_ID}" \
  -H "Authorization: Bearer $META_SYSTEM_USER_TOKEN" \
  --data-urlencode "fields=id,name"

1. 广告户查询核对返回的 id、name 和 account_status。
2. 主页查询核对返回的 id、name 是否对应投放要使用的主页。
3. 两次查询分别失败时，检查该对象的 System User 分配、API scopes、App 状态、Token 状态及 ID。保留脱敏后的 Meta 错误代码和消息用于排障。

C. 验证 ActionKey REST 服务凭证

先按环境变量说明设置 YURI_TOKEN 为 ActionKey 开通的服务凭证，再在同一终端执行：

curl --fail-with-body --silent --show-error \
  "https://baiz.ai/api/mcp/ad-accounts" \
  -H "Authorization: Bearer $YURI_TOKEN" \
  -H "Accept: application/json"

$yuriResult = Invoke-RestMethod -Method Get `
  -Uri 'https://baiz.ai/api/mcp/ad-accounts' `
  -Headers @{
    Authorization = "Bearer $env:YURI_TOKEN"
    Accept = 'application/json'
  }
$yuriResult

核对业务结果

ActionKey REST 响应要同时检查 HTTP 状态和 JSON 的 status。status: success 后，再核对 data 中的账户是否符合开通范围；status: error 时按 message 排查。Meta 原生 Graph 使用自己的数据与 error 结构，不套用 ActionKey REST 的业务字段。

REST 广告报表还可能返回 errors：即使返回部分数据，也要标出拉取失败的账户与缺失范围。任何路线完成预算或状态修改后，都应重新查询目标对象确认实际结果。

07 / 接口验证后，继续开发与编排

凭证和只读查询通过后，按你的工作方式进入对应教程。

• 聊天调用：在助手中发起具体指令，确认后执行操作。
• AI Agent 调用：配置目标、工具和停止条件，让 Agent 编排多个步骤。
• 开发自己的投放系统：从可运行 Python 示例开始，建设报表、审批、执行队列和任务调度。

自己的系统可以封装工具供 Agent 使用，也可以完全按业务代码运行；凭证仍由后端保管，操作范围以实际授权为准。

常见问题

怎么收费？

ActionKey 固定服务费为 人民币 ¥5,000 / 月，不限制请求数。Meta 广告消耗、AI 模型服务和运行环境费用另行承担。账户与操作范围按实际开通确认，Facebook 接口限流、审核及账户权限仍然适用。

原有 SDK 代码可以完全不改吗？

内部中转路线先修改凭证和域名；System User Token 原生路线使用 graph.facebook.com。不同 SDK 的基础地址配置、API 版本与接口支持各不相同，需以实际调用验证。

只生成 System User Token，为什么仍然无法创建广告？

核对生成 Token 时是否选择尤里改授权的 App、所需 API scopes 是否可用且已选择，以及对应 System User 是否分别拥有目标广告户和主页的任务权限。只读查询成功也不能证明写入权限完整。

Meta System User Token 可以直接填入 ActionKey MCP 吗？

不能默认互换。ActionKey MCP / REST 使用其开通的服务凭证；原生 System User Token 用于 Meta Graph API，或由你自己的后端工具封装后交给 Agent 调用。

Token 可以放到网页前端吗？

将凭证保存在服务端或受控 Agent 环境的凭证存储中，由后端代为调用。前端通过自己的业务接口请求数据与操作。

认证或权限错误怎么排查？

先核对凭证类型与域名，再检查 Token 状态、App、API scopes、ID 类型和资产任务权限。提供脱敏后的错误信息、请求方法与时间，联系微信 76762。

代理能绕过平台限制吗？

操作仍受 Facebook 接口规则、审核与风控约束，代理不会消除既有资产关联。服务提供已授权的操作能力，减少客户侧个户环境准备和维护环节。