下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/indiv-benjamin--sanlian-ads-ad-management.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md,安装 @indiv-benjamin/sanlian-ads-ad-management。Bilibili Sanlian Ads LEGACY three-level ad management (campaign-unit-creative, 计划-单元-创意). Use for saving, updating, querying and listing campaigns, units and creatives, creative audit information, one-click acceleration, the account smart-derivative switch, and asynchronous batch operations on campaigns, units and creatives with their task status and per-object results. These are the v3 endpoints; they cannot read or write creative-driven 2.0 projects and media. 中文触发词:计划、单元、创意、建计划、建单元、建创意、广告搭建、启停、批量操作、批量修改、一键起量、智能衍生、旧版广告。
阅读全文 (展开查看完整说明)
概述
Bilibili Sanlian Ads — Legacy Ad Management (计划 / 单元 / 创意)
The legacy three-level structure: campaign (计划) → unit (单元) → creative (创意). Campaigns carry the promotion purpose and budget, units carry targeting, schedule, bidding and optimization target, creatives carry the material and its presentation.
This skill also owns batch operations for these three levels, because batch operations only act on legacy objects.
Legacy Versus 2.0
The platform is moving to creative-driven delivery 2.0 (bilibili-sanlian-ads-delivery), a two-level project/media structure on /open_api/cpc/v4/*. Legacy will be phased out over time, but it remains the structure for all non-allowlisted accounts and for every ad created before an account was allowlisted.
The two are strictly separated:
- v3 endpoints here cannot read or write 2.0 projects or media, and v4 endpoints cannot read or write campaigns, units or creatives. Separate data models, separate ID spaces.
- Legacy ads cannot be upgraded. Rebuilding as a project plus media is the only path.
- An allowlisted account can no longer create legacy ads, but its existing legacy ads keep running and are still edited here.
If the user's account is allowlisted and they are creating something new, route to bilibili-sanlian-ads-delivery instead.
Usage Rules
- Confirm a valid
access_tokenand advertiseraccount_idfirst; usebilibili-sanlian-adswhen either is missing. - Every MAPI call goes through [
scripts/mapi.sh](scripts/mapi.sh) (on Windows usepy -3 scripts/mapi_client.py) —call <METHOD> <path> [--query-file q.json] [--body-file body.json]. It loads and refreshes the token, attaches the headers described below, enforces Rule 1 pacing, and applies the shared conservative error decision tree. It returns that classification with the raw response; endpoint-specific success and partial-success semantics still come from the reference below. Do not hand-writecurl,requestsorfetchfor a MAPI call, and never fan out across accounts or objects in parallel. - Base domain
https://cm.bilibili.com/takumi/api;Authorization: Bearer {access_token}; JSON bodies needContent-Type: application/json; every request needsX-Call-Source: sanlian-skillsandX-Sanlian-Skills-Version: 3.0.4. - Open the matching reference before composing any request. Required fields, conditional requirements, enums, mutually exclusive fields and examples all live in
references/. Do not invent fields or enum values, and do not probe by mutating a failing request. - Query selectable values from
bilibili-sanlian-ads-metadatabefore saving. A save fails, or silently sets something unintended, when an enum or resource ID was guessed. - For every create or edit, open
references/creation-field-source-map.mdin thebilibili-sanlian-ads-metadataskill. Every populated selectable value must have a traceable source from this run, current state or explicit user input. - Prepare images and videos with
bilibili-sanlian-ads-materialsbefore creating creatives. - Follow the sequential-call and error-stop discipline in
bilibili-sanlian-ads. Do not send another MAPI request until the previous one has completed and its response has been checked. - Do not re-save an object to verify it; query it instead. Do not retry a save that already succeeded. Prefer documented batch endpoints over loops of individual saves.
- Follow the main skill's operation brief, staged confirmation, canary and run-journal rules for every write. On edit, query current state first and show current → intended values.
- IDs are 64-bit integers. Parse them as 64-bit types.
When To Use
| Goal | Reference |
|---|---|
| Create or update a campaign | [references/505_计划保存.md](references/505_计划保存.md) |
| Query one campaign, or list campaigns | [references/506_计划查询.md](references/506_计划查询.md), [references/810_计划列表.md](references/810_计划列表.md) |
| Create or update a unit | [references/509_单元保存.md](references/509_单元保存.md) |
| Query one unit, or list units | [references/510_单元查询.md](references/510_单元查询.md), [references/811_单元列表.md](references/811_单元列表.md) |
| Create or update a creative | [references/524_创意保存.md](references/524_创意保存.md) |
| Query one creative, list creatives, or scroll-query creatives in bulk | [references/525_创意查询.md](references/525_创意查询.md), [references/812_创意列表.md](references/812_创意列表.md), [references/526_批量查询创意.md](references/526_批量查询创意.md) |
| Check native audit details for creatives | [references/528_批量查询创意原生审核信息.md](references/528_批量查询创意原生审核信息.md) |
| Check remaining unit budget, start or end one-click acceleration | [references/1673_一键起量.md](references/1673_一键起量.md) |
| Query or set the account-level creative smart-derivative switch | [references/1834_账户智能衍生状态查询.md](references/1834_账户智能衍生状态查询.md), [references/1835_账户智能衍生状态设置.md](references/1835_账户智能衍生状态设置.md) |
| Batch enable/pause/delete or edit campaigns, units, creatives | [references/541_批量操作计划.md](references/541_批量操作计划.md), [references/543_批量操作单元.md](references/543_批量操作单元.md), [references/544_批量操作创意.md](references/544_批量操作创意.md) |
| Check batch task status, then per-object results | [references/545_查询批量操作任务列表.md](references/545_查询批量操作任务列表.md), [references/546_查询批量操作任务详情.md](references/546_查询批量操作任务详情.md) |
Creation Order
Objects must exist top-down; a unit needs its campaign, a creative needs its unit.
- Confirm the operation brief, then open the creation field source map.
bilibili-sanlian-ads-metadata: query the promotion purpose required for the confirmed campaign branch.- Show the final campaign preview and confirm → save campaign → record and re-query
campaign_id. - Query only the metadata required for the confirmed unit: promotion content, promotion object, optimization target, bid range and targeting.
- Show the final unit preview and confirm → save unit → record and re-query
unit_id. - Prepare materials, then query creative placement/template constraints and the required deliverable resources.
- Show the final creative preview and confirm → save creative → record and re-query
creative_id; check audit status.
Approval of the overall goal does not approve later fields that were still unknown. Stop between levels when a newly returned ID, metadata result or platform constraint changes the preview.
Creative resources must be consistent with the creative location, template, promotion content, material type and audit requirements. A mismatch is rejected at save time, or passes save and fails audit.
Key Creation Rules And Conditional Constraints
- Unit Promotion Content (
promotion_content_type):- Values supported by unit save are
2lead generation (线索),4app download (应用包下载),6Android game centre (安卓游戏中心),8live room (直播间),20OGV promotion,21live reservation,60app deep link (应用唤起),61goods content (带货内容),62e-commerce URL (电商链接),63Taobao/Tmall goods,64content promotion (内容投放),65Bilibili mini game,66WeChat mini program,67Bilibili mini program,68Gravity Plan (引力计划), and69content monetization (内容变现). - Query endpoints may additionally return historical values
11dynamic goods (动态商品) and16game card (游戏卡). Do not use 11 or 16 in a new or edited unit save. - The list is a decoding aid, not permission to choose a value. Before every save, query the account's currently available values through metadata document 512 and use only a returned value compatible with the selected promotion purpose.
- Values supported by unit save are
- Unit Search Settings:
is_all_ad_search_unit: Boolean switch for using all ad search terms (0no,1yes).search_first_price_coefficient: First-position bid coefficient (1.00–2.00).
- Creative Monitor Attribution Type (
unit.monitor_attribution_type):- Conditional requirement: When the advertiser is an allowlisted account (白名单账户, account has enabled this capability), the campaign's promotion purpose is Trade (
PPT_TRADE=120), unit promotion content is Goods Content (61) or Goods URL (62), and the unit is not a child unit,monitor_attribution_typeis mandatory for both creation and updates in [references/524_创意保存.md](references/524_创意保存.md). - Allowed values:
1(impression attribution, 展示归因) or2(click and 3-second play attribution, 点击和3秒播放归因). - Validation errors: Omitting this field or passing
0when required returns归因方式不能为空. Passing any value other than1or2returns归因方式仅支持1-展示归因、2-点击和3秒播放归因. - Non-allowlisted accounts: If the account is not allowlisted or not in the effective scope, this parameter is ignored on create and preserved from existing settings on edit. External communication and skills describe this strictly as an "allowlisted account" (白名单账户) without disclosing internal account tags or specific implementation details.
- Conditional requirement: When the advertiser is an allowlisted account (白名单账户, account has enabled this capability), the campaign's promotion purpose is Trade (
Batch Operations
Batch endpoints exist to avoid loops of individual saves, but their documented maximum is not a target batch size. Use a conservative batch size and the main skill's canary/checkpoint protocol.
The shape is the same for all three levels: one operation_type per request, plus an operations array whose items carry the target IDs and the payload for that operation. A single request performs exactly one kind of operation — you cannot mix enable and budget changes in one call.
operation_type values:
- Campaign (
/batch/update_campaign): 1 enable, 2 pause, 3 delete, 4 change current budget, 5 change next-day budget. - Unit (
/batch/update_unit): 1 enable, 2 pause, 3 delete, 4 current budget, 5 next-day budget, 6 bid, 7 delivery dates, 8 dayparting, 9 extend delivery, 10 age targeting, 11 gender targeting, 12 area targeting, 13 crowd-pack targeting, 17 app-store direct launch, 18 custom search words, 19 negative search words, 22 bid coefficient, 23 delivery speed mode, 28 associated product, 33 audience bid coefficient, 34 converted-user filtering, 41 first-position bid coefficient. - Creative (
/batch/update_creative): 1 enable, 2 pause, 3 delete, 14 monitoring link, 15 change brand space, 16 change qualification, 20 call-up scheme, 35 cover, 36 title, 37 material description, 46 creative selling point. Operation 46 is now the only way to set a creative's promotion selling point: creative save (524) ignorespromotion_selling_pointand creative query (525) no longer returns it. Goods componentfeaturetext is unaffected.
Field structures for every one of these are in the three batch references. Note two easy mistakes: on creative, the cover and title fields are singular (image, title) even though they take arrays; on unit, ad_product_id is a string, and price_coefficient_type is a string too. Operation 22 always changes the search price coefficient; use operation 41 to change the first-position coefficient.
State transitions are constrained: enable applies only to paused objects, pause only to objects in delivery, delete only to objects not already deleted, and extend only to finished units. At most 100 IDs per operation item, no duplicates.
Use only the operation_type, payload fields and constraints documented in [references/541_批量操作计划.md](references/541_批量操作计划.md), [references/543_批量操作单元.md](references/543_批量操作单元.md) and [references/544_批量操作创意.md](references/544_批量操作创意.md). These official batch references are the complete capability source; do not maintain a separate supplemental capability list or infer support from task-history values.
Batch work is asynchronous:
- After execution confirmation, submit one-object canary (or the smallest valid batch) and capture
operation_id. - Poll the task list until terminal status. Back off — first check at 3s, then 3s / 5s / 10s / 20s, settling at 30s. Never poll tightly and do not start another MAPI sequence while waiting.
- Query task detail and inspect every per-object result. A completed task does not mean every object succeeded.
- Read back the canary where a query endpoint can verify the state, report the result, and ask before the remaining objects.
- Submit the next conservative batch only after the previous asynchronous task is terminal and fully checked. Stop on the first error or partial failure; never resend the original batch.
Budget and bid rules carry over from the save endpoints: budget is in yuan as a string with at most two decimals, minimum 500, and lowering a budget cannot take it below 1.2× the object's current daily spend. is_repeat only applies to operation_type=5. Do not mix "24-hour ROI" and non-ROI units in one bid-change request.
Confirm the exact objects, before → after values, canary and batch plan before submitting any batch write. High-impact batches require a checkpoint confirmation between batches.
One-Click Acceleration
Acceleration (一键起量) adds a separate budget on top of a unit's own budget to accelerate exploration and spend for a limited period. It takes effect immediately on enable, and ends automatically when the duration elapses or the acceleration budget is spent; the close endpoint ends it early.
- Only ocpc/ocpm units that are in delivery and have at least one deliverable creative are eligible.
- Query remaining unit budget first — the acceleration budget cannot exceed it, and must be above 500.
- Enable and close both process unit by unit. A top-level
status: successdoes not mean every unit succeeded: check each entry'soperate_code. - At most 20 units per call.
- Acceleration changes spend behaviour and costs real money. Confirm the account, the unit IDs, the amount and the intensity with the user before enabling.
Reading Responses
Business success or failure is carried in the response body, not the HTTP status. Check the envelope, then check per-object results wherever an endpoint reports them — batch tasks and acceleration both report per-object outcomes under a successful envelope.
On any error, timeout, partial per-object failure or unclear outcome, stop and run the main skill's cold re-check and support-packet workflow. Do not retry with modified fields to discover what the API wants, and do not continue later objects automatically.
Source Document Index
Synced from mapi/product/docs/开发者中心/MAPI接入/. doc_id matches the article ID on the developer site.
| Domain | Source document | Local reference | Endpoint |
|---|---|---|---|
| Campaign | 广告管理【旧】/计划管理/计划保存 (505) | [references/505_计划保存.md](references/505_计划保存.md) | POST /open_api/cpc/v3/campaign/save |
| Campaign | 广告管理【旧】/计划管理/计划查询 (506) | [references/506_计划查询.md](references/506_计划查询.md) | GET /open_api/cpc/v3/campaign/get |
| Campaign | 广告管理【旧】/计划管理/计划列表 (810) | [references/810_计划列表.md](references/810_计划列表.md) | GET /open_api/cpc/v3/campaign/list_campaigns |
| Unit | 广告管理【旧】/单元管理/单元保存 (509) | [references/509_单元保存.md](references/509_单元保存.md) | POST /open_api/cpc/v3/unit/save |
| Unit | 广告管理【旧】/单元管理/单元查询 (510) | [references/510_单元查询.md](references/510_单元查询.md) | GET /open_api/cpc/v3/unit/get |
| Unit | 广告管理【旧】/单元管理/单元列表 (811) | [references/811_单元列表.md](references/811_单元列表.md) | GET /open_api/cpc/v3/unit/list_units |
| Unit | 广告管理【旧】/单元管理/一键起量 (1673) | [references/1673_一键起量.md](references/1673_一键起量.md) | POST /open_api/cpc/v3/unit/get_remaining_budget, /unit/accelerate, /unit/finish_accelerate |
| Creative | 广告管理【旧】/创意管理/创意保存 (524) | [references/524_创意保存.md](references/524_创意保存.md) | POST /open_api/cpc/v3/creative/save |
| Creative | 广告管理【旧】/创意管理/创意查询 (525) | [references/525_创意查询.md](references/525_创意查询.md) | GET /open_api/cpc/v3/creative/get |
| Creative | 广告管理【旧】/创意管理/创意列表 (812) | [references/812_创意列表.md](references/812_创意列表.md) | GET /open_api/cpc/v3/creative/list_creatives |
| Creative | 广告管理【旧】/创意管理/批量查询创意 (526) | [references/526_批量查询创意.md](references/526_批量查询创意.md) | POST /open_api/cpc/v3/creative/scroll/query |
| Creative | 广告管理【旧】/创意管理/批量查询创意原生审核信息 (528) | [references/528_批量查询创意原生审核信息.md](references/528_批量查询创意原生审核信息.md) | POST /open_api/cpc/v3/creative/audit/extra/info/query |
| Creative | 广告管理【旧】/创意管理/创意智能衍生开关/账户智能衍生状态查询 (1834) | [references/1834_账户智能衍生状态查询.md](references/1834_账户智能衍生状态查询.md) | GET /open_api/cpc/v3/account/smart_derivative |
| Creative | 广告管理【旧】/创意管理/创意智能衍生开关/账户智能衍生状态设置 (1835) | [references/1835_账户智能衍生状态设置.md](references/1835_账户智能衍生状态设置.md) | POST /open_api/cpc/v3/account/smart_derivative |
| Batch | 广告管理【旧】/批量操作/批量操作计划 (541) | [references/541_批量操作计划.md](references/541_批量操作计划.md) | POST /open_api/cpc/v3/batch/update_campaign |
| Batch | 广告管理【旧】/批量操作/批量操作单元 (543) | [references/543_批量操作单元.md](references/543_批量操作单元.md) | POST /open_api/cpc/v3/batch/update_unit |
| Batch | 广告管理【旧】/批量操作/批量操作创意 (544) | [references/544_批量操作创意.md](references/544_批量操作创意.md) | POST /open_api/cpc/v3/batch/update_creative |
| Batch | 广告管理【旧】/批量操作/查询批量操作任务列表 (545) | [references/545_查询批量操作任务列表.md](references/545_查询批量操作任务列表.md) | GET /open_api/cpc/v3/batch/list_operations |
| Batch | 广告管理【旧】/批量操作/查询批量操作任务详情 (546) | [references/546_查询批量操作任务详情.md](references/546_查询批量操作任务详情.md) | GET /open_api/cpc/v3/batch/list_operation_details |