前言¶

投 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）。