前言¶

用 Agent 或脚本对接 B 站三连竞价推广 MAPI 时，计划、单元、创意保存接口里大量字段是枚举或资源 ID。这些值随广告主账户、推广目的、推广内容、投放位置变化，文档里的全量枚举也不能直接当成「当前账户可选集合」。若凭经验填数，常见结果是保存失败，或在用户未察觉时写入错误配置。

下面介绍 SkillHub 上的 B站三连广告-广告元数据（包内标识 bilibili-sanlian-ads-metadata）。它在任何保存请求组装之前，用只读查询把依赖项解析清楚；旧版三层创编与创意驱动 2.0 共用同一套元数据接口（个别能力如 2.0 模板组、旧版创意位置除外）。

这是什么¶

B站三连广告-广告元数据 是 B 站三连广告 MAPI Skill 族中的创编配置查询 Skill，作者 Benjamin，当前包版本 3.0.6，MIT 许可。SkillHub 分类为 business-ops；页面展示评分约 98055，下载约 2420 次（以 SkillHub 展示为准）。

定位一句话：只读解析保存请求所依赖的可选值，不创建、不修改广告对象。MAPI 侧查询需要有效的 access_token 与广告主 account_id（缺任一项时先走 bilibili-sanlian-ads 授权与账户范围）；另提供独立的 B 站公开稿件信息查询，仅需 BVID 或视频链接，无需广告账户。

官方入口：

• https://api.skillhub.cn/user_b0010d5c/sanlian-ads-metadata
• https://skillhub.cn/skills/user_b0010d5c/sanlian-ads-metadata

核心功能¶

Skill 将官方「创编配置查询」文档同步到 references/，按场景索引接口。经包内 SKILL.md 核实的主要能力如下。

创编链路元数据¶

素材与创意相关资源¶

• 稿件与视频：可投放稿件（531）、稿件 MID（529）、本地视频（530）、开放空间 MID（536）、合伙人授权任务（538）。
• 动态：四条来源分别对应 532–535（可用 MID、MID 下动态、手动绑定、花火商单），不可混用。
• 试玩、落地页、卖点：试玩素材（1829）、高能建站落地页（537）、暂停广告落地页（1887）、推广卖点（1942）。
• 组件：稿件配置组件（1722）、直播间游戏卡组件（1699）；组件创建在 bilibili-sanlian-ads-assets，本 Skill 只查询已存在配置。
• 旧版创意位置：527（仅 legacy 三层结构；2.0 通过 bilibili-sanlian-ads-delivery 的模板组与 promotion_scene 表达）。

公开稿件信息（非 MAPI）¶

用户提供 BVID 或 https://www.bilibili.com/video/{bvid} 时，可调用 B 站公开接口 GET https://api.bilibili.com/x/web-interface/view 获取 avid、bvid、UP 主、标题、简介、封面、分 P 等。不代表广告授权或可投放性，也不应因此自动触发 531 等 MAPI 查询。

工作约束（Skill 内建规则）¶

1. MAPI 调用统一经包内 scripts/mapi.sh（Windows 用 py -3 scripts/mapi_client.py），基址 https://cm.bilibili.com/takumi/api，需 Authorization: Bearer {access_token}、X-Call-Source: sanlian-skills、X-Sanlian-Skills-Version: 3.0.4（以 Skill 文档为准）。
2. 公开稿件查询不得走 mapi.sh call；需普通 HTTP 客户端，并设置浏览器形态 User-Agent，否则可能遇到 HTTP 412。
3. 创编前打开 references/creation-field-source-map.md，每个填入保存体的值都要有可查来源；空结果表示当前账户不可用，禁止回落到硬编码枚举。
4. 查询顺序遵循依赖链：推广目的 → 推广内容 → 推广对象 → 优化目标/出价 → 定向 → 位置 → 可投素材 → 落地页/卖点等附件。

安装与启用¶

SkillHub 官方页提供安装或下载 Skill 包入口。若需直链拉取压缩包（经 SkillHub 下载 API 可访问），可使用：

curl -L "https://api.skillhub.cn/api/v1/download?slug=sanlian-ads-metadata&namespace=indiv-benjamin" \
  -o sanlian-ads-metadata.zip

解压后按你所用 Agent 的 Skill 目录规范放入即可（Cursor、Claude Code 等具体挂载路径以各自文档为准，本 Skill 包内未单独区分）。

运行环境要求（来自同族 MAPI 客户端说明）：Python 3.8+，无第三方依赖。首次调用 MAPI 元数据前，应已安装并初始化 bilibili-sanlian-ads，完成 OAuth 与 account_id 确认。

典型用法¶

1. 创编前查推广目的（507）¶

先确认账户与令牌，再查当前账户可选推广目的。查询参数示例：

{
  "account_id": 123456
}

通过 Skill 自带客户端发起 GET（路径以 references/507_查询计划可用推广目的.md 为准）：

cd /path/to/sanlian-ads-metadata
scripts/mapi.sh call GET /open_api/launch/cpc/meta_data/v3/campaign/get_promotion_purpose_type \
  --query-file query.json

返回体中的 result 数组给出 promotion_purpose_type 及描述；后续 512、513 等查询应基于这里选定的目的继续，而不是使用 1711 枚举大全代替账户可选集。

2. 按依赖链推进单元配置¶

在 bilibili-sanlian-ads-ad-management 或 bilibili-sanlian-ads-delivery 保存之前，Skill 建议的顺序为：

1. 507 确定推广目的；
2. 512 确定推广内容；
3. 按内容类型调用 514/519/518/515 等获取推广对象；
4. 513、522 确定优化目标与出价区间；
5. 520 拉取定向维度；
6. legacy 用 527 查创意位置，2.0 转 delivery Skill 查模板组；
7. 531/530/532–535 等按素材类型查可投放资源；
8. 537、1942、1722 等补齐落地页与卖点。

每一步只发起一个查询，读完响应再进入下一步；同一账户、同一任务内可缓存已查结果，避免重复打接口。

3. 仅凭 BVID 查公开稿件¶

curl --location --request GET \
  'https://api.bilibili.com/x/web-interface/view?bvid=BV1GpC7BCE74' \
  -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'

检查 code 是否为 0，再按需提取 data.aid、data.title、data.owner 等；长整型 ID 建议按字符串保存。

适用场景与注意¶

适合谁

• 通过 Agent 做三连广告创编、改单、对账前校验字段的开发者或运营；
• 需要把「用户给的 BV 链接」转成结构化稿件信息，再人工判断是否走授权与可投放查询的场景。

限制与常见坑

• 本 Skill 不上传素材；图片视频走 bilibili-sanlian-ads-materials，授权关系走 bilibili-sanlian-ads-assets。
• 531 返回的 media_id 用于 2.0；530 的 video.material_id 是创意中心素材 ID，与 media_id 不是同一 ID 空间。
• B 小程序与小游戏共用 1697，用 sort=0（小程序）与 sort=2（小游戏）区分。
• MAPI 业务成败看响应体而非 HTTP 状态码；200 仍可能带业务错误，需对照对应 references 文档解读。

同族路由参考：bilibili-sanlian-ads 负责授权与任务分发；保存计划/单元/创意用 bilibili-sanlian-ads-ad-management（legacy）或 bilibili-sanlian-ads-delivery（2.0）。创编类任务应先加载本元数据 Skill，再进入保存类 Skill。

结尾¶

B站三连广告-广告元数据 把创编保存所依赖的可选值查询收敛成一套只读工作流，并单独覆盖公开稿件信息解析，减少枚举猜测带来的失败与误配。需要安装或更新时，以 SkillHub 官方页为准：https://api.skillhub.cn/user_b0010d5c/sanlian-ads-metadata