Bilibili Sanlian Ads MAPI Ad Management

Use this skill for the three core ad object levels: campaign, unit, and creative. It handles save/create/update, detail query, list query, creation orchestration, copy workflows, and safe fallback when batch operations do not support a requested change.

Use bilibili-sanlian-ads-metadata for selectable values and deliverable resources. Use bilibili-sanlian-ads-materials for image/video/archive material preparation. Use bilibili-sanlian-ads-batch-operations for supported batch updates and deletions.

Usage Rules

• Confirm a valid access_token and advertiser account_id first. Use bilibili-sanlian-ads when either is missing.
• Open the matching reference before composing any request. Required fields, conditional requirements, object structures, enum values, and examples live in references/.
• Business APIs use https://cm.bilibili.com/takumi/api as the root path and usually require Authorization: Bearer {access_token}.
• Every MAPI request must include X-Call-Source: sanlian-skills, even when a reference example omits it.
• Pass fields in the exact location specified by the reference: query, JSON body, multipart form data, or form data.
• Campaign support_auto is fixed to 1. Do not send it when creating a campaign; regardless of request value, the effective value is 1.

Hierarchy Model

• Campaign, unit, and creative form a strict tree: campaign -> unit -> creative.
• A unit must belong to one existing campaign. A creative must belong to one existing unit.
• IDs at every level are globally unique, but uniqueness does not remove the hierarchy requirement.
• When a user asks to create a unit, first confirm which campaign it belongs to. If the user has not clearly provided an existing campaign or requested a new campaign, ask whether to create a new campaign or use an existing campaign.
• When a user asks to create a creative, first confirm which unit it belongs to. If the user has not clearly provided an existing unit or requested a new unit, ask whether to create a new unit or use an existing unit.
• If the user asks to create a full campaign/unit/creative tree, create it in order and carry forward returned IDs from each save response.

Write Ordering

• Do not call save APIs concurrently. Save calls must be serialized even if parallel execution looks faster.
• Wait for each save response before starting the next dependent save. Use returned campaign_id, unit_id, and creative_id_list from the prior response.
• Serial execution is slower, but it is more stable for these APIs and prevents one failed dependent call from obscuring the real failing step.
• If a save step fails, stop the creation chain, report the failed level, request payload summary, API error code/message, and already-created upstream objects.

When To Use

Endpoint Map

Creation Policy

• If the user specifies the ad type or creation target clearly, use the provided values directly and attempt creation.
• Do not pre-block creation by exhaustively checking metadata when the user already gave clear parameters. If save fails, then query the relevant metadata APIs and tell the user what is currently available.
• For campaigns, use metadata only when the promotion purpose or other selectable values are missing, ambiguous, or needed after a save error.
• For units, use metadata only when promotion content, optimization targets, targeting, bid range, app/game/goods/live resources, or other selectable values are missing, ambiguous, or needed after a save error.
• For creatives, if the user directly provides a target archive, video, image, material, title, or description, use it directly. If creative save fails because the resource is unavailable or invalid, report that result and ask the user how to proceed.

Delete And Cleanup

• If the creation process creates the wrong campaign, unit, or creative, or if the user's task requires deleting created content, use bilibili-sanlian-ads-batch-operations.
• Deletion is sensitive. Never delete without explicit user confirmation.
• Before deleting, clearly list the exact objects to delete: level, name if known, ID, account ID, and why deletion is proposed.
• After user confirmation, submit the batch delete operation, poll the batch task result, then re-query affected objects or task details and report the final result.

Batch Change Fallback

• First check whether bilibili-sanlian-ads-batch-operations supports the requested batch change.
• If the batch API supports it, use the batch API after a dry-run summary and explicit user confirmation.
• If the user asks to batch modify a field that batch APIs do not support, modify objects one by one through save APIs.
• For save-based fallback, always query the current object detail first, replace only the user-requested content, then reassemble the save request from the queried detail.
• Because save APIs can behave like full saves and field structures are large, there is risk of dropping fields during reassembly. Be deliberately conservative.
• After saving the first ad object in a fallback run, stop and ask the user to confirm that the logic and resulting object are correct before continuing.
• After every account, or every 10 modified ads, stop again and ask the user to inspect before continuing.
• After each save, re-query the object and verify that only the requested content changed. If any unrelated field changed, notify the user immediately.
• If any API call errors or returns unexpected data, stop and ask the user to inspect or confirm next steps.
• At completion, re-query all affected objects and produce an execution report covering target IDs, requested change, executed method, success/failure, API errors, verification result, and any unrelated field drift.

Copy Workflows

• Copying an ad means: query the source object details -> extract fields needed for creation -> create a new object.
• If the user asks to copy a campaign, clarify whether to also copy units and creatives unless the request already says so.
• If the user asks to copy a unit, ask whether to copy it into an existing campaign or create/copy a campaign for it. Also ask whether to copy its creatives.
• If the user asks to copy a creative, confirm the destination unit unless it is already provided.
• Even when copied content is identical, creation can fail because accounts, campaigns, units, allowlists, materials, resources, or permissions differ.
• If copy creation fails, report the API error clearly and ask the user what to do next. Do not silently substitute other assets or settings.

BVID Creative Flow

• If the user provides only a BVID or Bilibili video URL like https://www.bilibili.com/video/{bvid} for creative creation, ask whether to reuse the video's cover, title, and UP name.
• If the user does not want to reuse them, ask for the specific cover, title, description, and other required creative inputs.
• If the user agrees to reuse them, call the public Bilibili video API in references/bilibili_公开稿件信息查询.md.
• Use data.pic as the cover URL, then use bilibili-sanlian-ads-materials image URL import to obtain a material ID.
• Use data.owner.name as the creative description and data.title as the creative title only after checking length, emoji, and unsupported characters.
• Use data.aid as the archive ID for the creative. Preserve it as a string if the runtime may lose integer precision.
• If title or UP name is too long or contains unsupported characters, ask the user whether to discard, shorten, replace, or provide custom text. Do not silently rewrite.

Query And Sync Guidance

• Detail APIs (campaign/get, unit/get, creative/get) are best when an exact ID is known and the goal is edit-before-save, copy, or verification.
• List APIs are best for sync. For full data, sync by day. For incremental data, filter by same-day mtime, but remember some returned fields may not update mtime.
• start_ctime/end_ctime and start_mtime/end_mtime list filters use millisecond timestamps; each start/end span must not exceed 24 hours.
• List ID filters are comma-separated strings. campaign_ids, unit_ids, and creative_ids allow at most 100 IDs in list APIs.
• Query APIs can return long integer IDs. Preserve IDs as strings if the runtime may lose integer precision.

Source Document Index