前言¶

用 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