前言¶

投 B 站三連廣告時，創意往往卡在素材側：封面要按版位規格上傳，視頻要先拿預簽名地址再直傳對象存儲，稿件還要等異步處理；多賬戶投放時還要推送素材、用標籤歸類。手工在開放平臺文檔和 Postman 之間切換，容易漏請求頭、把預簽名上傳當成 MAPI 調用，或在處理未完成時就繼續建創意。

下面介紹 SkillHub 上的 B站三連廣告-素材上傳（包名 bilibili-sanlian-ads-materials）。它把三連廣告 MAPI 的素材管理接口整理成 Agent 可執行的 SKILL.md 與參考文檔，並附帶統一的 mapi.sh 客戶端，讓模型按規則串行調用，而不是臨時拼 curl。

這是什麼¶

B站三連廣告-素材上傳 是面向 B 站三連廣告（Sanlian Ads）的素材管理 Skill：圖片上傳與刪除、視頻預簽名上傳與稿件創建、處理進度查詢、可投稿 UP 主 MID 查詢、素材標籤與綁定、跨廣告主賬戶素材推送。

• 維護方：SkillHub 社區作者 Benjamin（頁面展示名「本傑明」），MIT 許可；Skill 標識爲 @indiv-benjamin/sanlian-ads-materials，當前版本 3.0.5。
• 發佈渠道：SkillHub 技能頁（官方入口亦見 api.skillhub.cn 用戶頁）。
• 前置依賴：需有效的三連廣告 access_token 與廣告主 account_id；缺憑證時由同系列的 bilibili-sanlian-ads 處理授權。SkillHub 元數據標註 requires_api_key: true。
• 與投放的關係：素材入庫後，可交付狀態由 bilibili-sanlian-ads-metadata 查詢；掛到計劃/創意或創意驅動 2.0 的 media，分別走 bilibili-sanlian-ads-ad-management 與 bilibili-sanlian-ads-delivery。

中文對話裏可用觸發詞：素材、上傳圖片、上傳視頻、稿件上傳、素材標籤、素材推送、創意中心、封面、視頻處理進度。

核心功能¶

以下能力均來自 Skill 自帶的 SKILL.md 與接口參考文檔（同步自 B 站開發者中心「素材管理」文檔）。

圖片¶

• 本地文件上傳：…/v3/creative/upload_pic
• URL 上傳（已託管圖片時優先，避免 multipart）：…/v3/creative/upload_pic_with_url
• 列出現有圖片：…/meta_data/launch/medias（上傳前建議先查，避免重複素材）
• 刪除圖片：…/v3/file/image/delete

版位、尺寸、格式等約束按接口文檔逐項覈對，不能從圖片規格類推視頻。

視頻與稿件¶

典型鏈路分 MAPI 與 非 MAPI 兩步，混用鑑權是常見踩坑點：

1. 調 MAPI 獲取預簽名 URL：…/meta_data/signed_urls（需 Bearer token）。
2. 用普通 HTTP 客戶端 PUT 視頻文件到預簽名 URL：不要帶 Bearer，不要帶 X-Call-Source。
3. 調 MAPI 批量創建稿件：…/meta_data/create/archives。
4. 輪詢處理進度：按處理 ID（…/archive/progress）或文件 MD5（…/archive/v1/progress）；處理異步，需退避輪詢，未到終態不要並行開下一條 MAPI 序列。
5. 查詢賬戶可投稿的 UP 主 MID：…/meta_data/enterprise/mid（授權流程在 bilibili-sanlian-ads-assets）。

本地計算的 文件 MD5 建議保留：無 processing id 時可查進度；創意驅動 2.0 下本地視頻註冊 media_id 時會用到 cm_video.file_md5。

素材標籤¶

標籤的增刪改查、與素材綁定、按標籤列素材等，路徑在 …/v3/resource/material_tag/ 下（如 list/page、batch_insert、bind、list_material 等）。刪除標籤會全局解綁，Skill 要求先與用戶確認。

素材推送¶

…/meta_data/v3/file/material/bind 將素材推送到其他廣告主賬戶，避免重複上傳。因會寫入他人賬戶，必須明確確認目標賬戶列表。

安裝與啓用¶

1. 安裝 SkillHub CLI（未安裝時）¶

command -v skillhub && skillhub --version

若未安裝，可僅裝 CLI：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安裝說明見 SkillHub 安裝文檔。

2. 安裝本 Skill 到當前 Agent 的 skills 目錄¶

安裝時必須用 --dir 指向當前工具識別的目錄，否則默認落在 ./skills/ 可能不會被加載。

skillhub install sanlian-ads-materials --dir ~/.cursor/skills

各客戶端常見路徑（與官方文檔一致）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex CLI：~/.codex/skills/ 或項目下 .agents/skills/

也可在 SkillHub 技能頁下載 Zip，解壓到上述目錄。本 Skill 不通過 npx skills add 從 GitHub 安裝；三連繫列在 SkillHub 分發。

3. 運行環境¶

• Python 3.8+：MAPI 由 Skill 內 scripts/mapi.sh（Linux/macOS）或 py -3 scripts/mapi_client.py（Windows）執行；可通過環境變量 SANLIAN_PYTHON 指定解釋器。
• 三連憑證：客戶端從本機憑證存儲或 BILIBILI_MAPI_CREDENTIALS 等配置讀取 token（細節由主 Skill bilibili-sanlian-ads 約定）；client_secret 也可經 BILIBILI_MAPI_CLIENT_SECRET 提供。

安裝或更新後，按你所用 Agent 的要求重啓或刷新 Skill 列表。

典型用法¶

MAPI 統一入口¶

除預簽名視頻 PUT 外，所有 MAPI 請求應經 Skill 目錄下的客戶端，不要手寫 curl/requests 對 cm.bilibili.com 直連，也不要並行多賬戶、多對象刷接口。

在 Skill 根目錄下，調用形式爲：

./scripts/mapi.sh call <METHOD> <path> [--query-file q.json] [--body-file body.json]

客戶端會處理 token 刷新、請求頭與三連 Skill 約定的限速與錯誤分類。MAPI 基域爲 https://cm.bilibili.com/takumi/api；JSON 請求需 Content-Type: application/json，並帶 Authorization: Bearer {access_token}、X-Call-Source: sanlian-skills、X-Sanlian-Skills-Version: 3.0.4（以 Skill 文檔爲準）。

業務成敗以響應體爲準，而非 HTTP 狀態碼；批量接口要逐項看單條結果。

與 Agent 協作時的操作順序¶

1. 確認 access_token 與 account_id（無則先走 bilibili-sanlian-ads）。
2. 根據目標打開對應 references/ 文檔（如 1890_圖片管理.md、1889_視頻管理.md），按文檔拼 body.json / query.json。
3. 圖片：必要時先 launch/medias 查重，再 upload_pic 或 upload_pic_with_url。
4. 視頻：signed_urls → 外部 PUT → create/archives → 輪詢 progress；記錄 MD5。
5. 標籤或跨賬戶推送：先與用戶確認刪除/目標賬戶，再調用對應接口。

上傳非冪等：失敗重試前應先確認是否已成功，避免重複素材。

適用場景與注意¶

適合誰

• 用 Cursor、Claude Code、Codex 等帶 Skills 的 Agent，需要穩定對接三連素材 MAPI 的投放、運營或集成開發。
• 已在用同系列 Skill 做創編或報表，希望把「上傳—處理—標籤—推送」從創意保存裏拆出來單獨維護。

限制與注意

• 只覆蓋素材管理 MAPI，不包含 OAuth 全流程（依賴 bilibili-sanlian-ads）與資產授權（bilibili-sanlian-ads-assets）。
• 視頻預簽名上傳與 MAPI 的鑑權、報錯形態完全不同；預簽名過期需重新申請 URL，不要盲重試舊鏈接。
• 刪除圖片或標籤、素材推送到其他賬戶前，Skill 要求顯式確認，避免誤傷在投創意。
• SkillHub 安全掃描（Keen、三不）當前爲「安全，無風險」；仍應只在受信環境存放 token 與 client_secret。

結尾¶

B站三連廣告-素材上傳 把三連廣告素材側的高頻接口和「預簽名直傳 vs MAPI」邊界寫進 Skill 規則，配合 mapi.sh 減少 Agent 誤調接口。若你正在搭三連投放自動化鏈路，可先裝此 Skill 處理素材，再銜接 metadata 與創編 Skill。

官方入口：https://api.skillhub.cn/user_b0010d5c/sanlian-ads-materials（瀏覽頁：https://skillhub.cn/skills/user_b0010d5c/sanlian-ads-materials）。