shield_lock
JinDaGe
← Back to skills
extension
Category: OtherAPI key required

bilibili-mapi-workflow

Start-here global orchestration guide for Bilibili MAPI advertising workflows. Use this skill first for end-to-end tasks such as OAuth authorization, account discovery, material upload, creating ads through campaign/unit/creative (计划/单元/创意), querying ads, reporting spend, batch operations, budgets/funds, RTA, and cleanup. This skill routes agents to the smaller endpoint-specific Bilibili MAPI skills.

personAuthor: user_b0010d5chubcommunity
downloadDownload package

Bilibili MAPI Global Workflows

This skill is the global workflow guide for Bilibili MAPI advertising operations. It does not replace endpoint-level documentation. When a workflow reaches a specific API call, open the corresponding atomic skill's SKILL.md and its references/ files, then use the original API documentation as the source of truth for request fields, response fields, enums, conditional requirements, and error handling.

Core Rules

  • First identify the user's actual goal: OAuth authorization, account discovery, material upload, ad creation, ad query, data/report query, batch operation, budget/funds, RTA, one-click acceleration, or cleanup.
  • Most business APIs require both an access_token and an advertiser account_id. If there is no token, start with bilibili-mapi-auth. If there is no account ID, use bilibili-mapi-account-list.
  • Do not use local historical tokens, historical account IDs, or cached results unless the user explicitly asks you to. For single-session experiments, only use information provided by the user in the current session or returned by APIs in the current session.
  • Before calling any write API, read the relevant save/update/batch skill reference. Many Bilibili MAPI fields are conditionally required, so this workflow should not guess field sets.
  • Treat rate-limit or frequency-control errors as retryable. If an API response sounds like frequency control, QPS limit, traffic limit, rate limit, quota throttling, "频控", "QPS 不够", "请求过于频繁", or similar, wait 3 seconds and retry once. If it happens again, wait 5 seconds and retry. If it happens a third time, wait 10 seconds and retry. Preserve the final error if all retries fail.
  • Keep key bilingual terms consistent: campaign (计划), unit (单元), creative (创意), archive/submitted video (稿件), material (素材), targeting (定向), optimization target (优化目标).

Skill Routing Table

| User goal | Use this skill first | |---|---| | OAuth authorization, token exchange, token refresh, authorized user check | bilibili-mapi-auth | | List authorized subjects, filter subject_type=1, list advertiser accounts, get account details | bilibili-mapi-account-list | | Query account funds, balance, and daily budget | bilibili-mapi-account-funds | | Query or set account budget and next-day budget | bilibili-mapi-account-budget | | Query account cash flow | bilibili-mapi-account-cashflow | | Create or update campaign (计划) | bilibili-mapi-campaign-save | | Query campaign (计划) | bilibili-mapi-campaign-query | | Create or update unit (单元) | bilibili-mapi-unit-save | | Query unit (单元), unit list, or remaining budget | bilibili-mapi-unit-query | | Query unit metadata: promotion content, optimization targets, targeting dimensions, apps, games, products, live rooms | bilibili-mapi-unit-meta | | Enable or disable one-click acceleration | bilibili-mapi-unit-accelerate | | Create or update creative (创意) | bilibili-mapi-creative-save | | Query creative (创意), creative list, preview, or audit information | bilibili-mapi-creative-query | | Query usable creative resources such as submitted videos, dynamics, landing pages, playable materials, and creative placements | bilibili-mapi-creative-resource | | Query creative exploration, archive components, smart derivatives, and paused-ad landing pages | bilibili-mapi-creative-derivative | | Upload image materials, import image URLs, list/push/delete image materials | bilibili-mapi-material-image | | Upload videos through signed URLs, create submitted videos, query processing progress, list allowed submission MIDs | bilibili-mapi-material-video | | Create, bind, unbind, query, or manage material tags | bilibili-mapi-material-tag | | Query custom reports, spend, impressions, clicks, conversions, and delivery data | bilibili-mapi-report-custom | | Batch update campaigns, units, or creatives | bilibili-mapi-batch-campaign / bilibili-mapi-batch-unit / bilibili-mapi-batch-creative | | Query batch task status and details | bilibili-mapi-batch-status | | Cleanup tools, inefficient units, scan rules, and unit quota | bilibili-mapi-batch-cleanup | | RTA groups, RTA IDs, binding status, enable/disable RTA | bilibili-mapi-rta |

Basic Preparation Flow

For any task that operates on a real advertiser account, confirm these two prerequisites first:

  1. A usable access_token for the current session.
    • If there is no token, use bilibili-mapi-auth.
    • If the token is expired, refresh it through bilibili-mapi-auth. If there is no refresh_token or refresh fails, restart authorization.
  2. A target advertiser account_id for the current session.
    • If there is no account ID, use bilibili-mapi-account-list.
    • Account discovery must filter authorized subjects to subject_type=1, which means brand bank workbench organization (品牌银行工作台-组织). Do not use subject_type=2 or subject_type=3 for later delivery operations even if the API returns them.

Workflow 1: OAuth Authorization To Operable Account

Use this when the user is authorizing for the first time, the token is invalid, or available advertiser accounts must be listed.

  1. Use bilibili-mapi-auth.
  2. Ask the user for client_id and client_secret. Do not ask for redirect_uri at the beginning.
  3. Open the authorization link and ask the user to authorize.
  4. After the user sends back the full callback URL, extract code from the URL. Use the same callback URL without query or fragment as the token request's redirect_uri.
  5. Exchange the code for access_token and refresh_token.
  6. Optionally call the user info endpoint to verify the authorized user.
  7. Switch to bilibili-mapi-account-list.
  8. Query subjects and keep only subject_type=1.
  9. Query advertisers to get operable account_id values.
  10. If account display details are needed, query account detail.

Recommended output: list the account ID, account name, subject ID, and clearly state that the data came from the current session.

Workflow 2: Query Today's Or A Specific Date's Spend

Use this when the user asks how much was spent today, asks for account delivery data, or requests a report.

  1. Confirm token and account ID. Use the basic preparation flow if needed.
  2. Use bilibili-mapi-report-custom.
  3. Query a single-day custom report. For multi-day reports, loop by day instead of putting multiple dates into one request.
  4. Prefer charged_cost_milli for spend. Convert to yuan with: yuan = charged_cost_milli / 100000.
  5. Common metrics:
    • Spend: charged_cost_milli
    • Impressions: show_count
    • Clicks: click_count
  6. If the user asks about cash flow, balance, or account fund changes instead of delivery-report spend:
    • Balance/budget: bilibili-mapi-account-funds
    • Cash flow: bilibili-mapi-account-cashflow

Note: custom reports usually return only rows with delivery cost. An empty array usually means no spend under that dimension, not necessarily an API failure.

Workflow 3: Upload Image Material

Use this when the user wants to upload an image, import an image from a URL, or push material to another account.

  1. Confirm token and account ID.
  2. Use bilibili-mapi-material-image.
  3. Use Upload image for local image files. Use Import image by URL for remote image URLs.
  4. After receiving the image material ID:
    • Use it in creative creation if the user is building an ad.
    • Push it to another account if requested.
    • Switch to bilibili-mapi-material-tag if tags are needed.

Note: local upload, URL import, push, and delete operations use different Content-Type values and field locations. Follow the reference exactly.

Workflow 4: Upload Video And Create Submitted Video (稿件)

Use this when the user wants to upload a video material, create a submitted video/archive (稿件), or query processing progress.

  1. Confirm token and account ID.
  2. Use bilibili-mapi-material-video.
  3. Query a signed upload URL.
  4. Upload the video file with PUT to the signed URL. This request does not use the MAPI root path; call the signed URL directly.
  5. Batch create submitted videos/archive (稿件).
  6. Poll processing progress. Querying by MD5 is recommended.
  7. After the submitted video becomes usable for delivery, continue to creative resource query or creative creation.

Workflow 5: Main Ad Creation Flow

Use this when the user says they want to create an ad, create delivery, or set up an ad structure.

Recommended order:

  1. Basic preparation: bilibili-mapi-auth -> bilibili-mapi-account-list.
  2. Pre-creation metadata:
    • Available campaign promotion goals: bilibili-mapi-campaign-query
    • Available unit promotion content, optimization targets, targeting dimensions, apps, games, products, live rooms: bilibili-mapi-unit-meta
    • Available creative placements, submitted videos, dynamics, landing pages, playable materials: bilibili-mapi-creative-resource
  3. Material preparation:
    • Images: bilibili-mapi-material-image
    • Videos/submitted videos (稿件): bilibili-mapi-material-video
    • Material tags: bilibili-mapi-material-tag
  4. Create campaign (计划): bilibili-mapi-campaign-save.
  5. Create unit (单元): bilibili-mapi-unit-save.
  6. Create creative (创意): bilibili-mapi-creative-save.
  7. Post-creation verification:
    • Query campaign: bilibili-mapi-campaign-query
    • Query unit: bilibili-mapi-unit-query
    • Query creative, preview, and audit status: bilibili-mapi-creative-query

Key constraints:

  • Campaign (计划), unit (单元), and creative (创意) have a strict hierarchy: a unit must belong to a campaign, and a creative must belong to a unit.
  • Before creating a unit, there must be a campaign_id. It may come from a campaign created in this session or from an existing campaign ID explicitly provided by the user.
  • Before creating a creative, there must be a unit_id. It may come from a unit created in this session or from an existing unit ID explicitly provided by the user.
  • When the user says "create an ad", do not assume they have provided a complete parameter sheet. First inspect the campaign-save, unit-save, and creative-save references to identify the minimum required fields and the conditionally required fields for the current scenario, then ask the user only for the missing business information that blocks progress.
  • Ad creation may require multiple rounds of parameter completion. Collect the fields that can be determined, assemble the request, and try the API. If the API reports missing fields, invalid enums, unmet conditions, or unavailable materials/resources, ask the user for the specific missing or corrected information and continue. Do not stop after a single failed attempt.
  • If the user provides metadata or IDs such as promotion goal, optimization target, targeting, material ID, submitted video ID, creative placement, budget, or bid, trust and use them first. Return to metadata queries or ask the user again only if the API returns an error, the metadata is inconsistent, or the reference explicitly requires validation.
  • When information is missing, prioritize questions about fields that block creation. Do not force the user to complete an excessively long form upfront. For complex ad creation, split the work into three stages: campaign (计划), unit (单元), and creative (创意).
  • Do not skip metadata queries. Unit save and creative save depend on many enums, placements, promotion content options, optimization targets, and targeting fields from metadata APIs.
  • Materials/resources used by a creative must match the creative placement, template, promotion content, and audit requirements.
  • If the task involves brand qualification, account qualification, brand space, or qualification packages, and the current skills do not cover the corresponding APIs, tell the user that the current skill set may be missing qualification-related endpoints.

Workflow 6: Query Existing Ad Structure

Use this when the user wants to query existing ads, list campaigns/units/creatives, or verify creation results.

  1. Confirm token and account ID.
  2. Query campaign:
    • Campaign detail or list: bilibili-mapi-campaign-query
  3. Query unit:
    • Unit detail, unit list, remaining budget: bilibili-mapi-unit-query
  4. Query creative:
    • Creative detail, list, batch query, preview, audit information: bilibili-mapi-creative-query
  5. If referenced resource details are needed, also query:
    • bilibili-mapi-creative-resource
    • bilibili-mapi-material-image
    • bilibili-mapi-material-video

Recommended output: organize results by campaign_id -> unit_id -> creative_id.

Workflow 7: Batch Operations

Use this for batch pause, enable, delete, budget change, bid change, targeting change, and similar operations.

  1. Confirm token and account ID.
  2. Query the current objects first to avoid unintended changes:
    • Campaign: bilibili-mapi-campaign-query
    • Unit: bilibili-mapi-unit-query
    • Creative: bilibili-mapi-creative-query
  3. Choose by object type:
    • Batch campaign: bilibili-mapi-batch-campaign
    • Batch unit: bilibili-mapi-batch-unit
    • Batch creative: bilibili-mapi-batch-creative
  4. Submit the batch operation and capture the batch task ID.
  5. Use bilibili-mapi-batch-status to query task list and task details.

Note: batch operations are usually asynchronous. Do not assume success immediately after submission; query task details.

Workflow 8: Budget, Funds, And Cash Flow

Use this to query balance, query budget, set budget, or query account cash flow.

  1. Confirm token and account ID.
  2. Query current account funds and daily budget: bilibili-mapi-account-funds.
  3. Query or set account budget and next-day budget: bilibili-mapi-account-budget.
  4. Query account cash flow: bilibili-mapi-account-cashflow.

Measurement reminders:

  • Delivery report spend uses bilibili-mapi-report-custom.
  • Cash flow spend fields are not the same as delivery report spend, and may exclude incentive coupon consumption.
  • If the user asks for delivery spend, use report custom first. If the user asks for account fund changes or cash flow, use cash flow.

Workflow 9: Material Tag Management

Use this to create material tags, bind materials, unbind materials, or query materials by tag.

  1. Confirm token and account ID.
  2. Use bilibili-mapi-material-tag.
  3. Common order:
    • Create a material tag.
    • Query tag list to get tag_id.
    • Bind image/video materials.
    • Query materials under a tag.
    • Update, unbind, or delete when needed.

Note: deleting tags or unbinding materials may affect automated delivery or material-hosted creatives. Confirm with the user before executing.

Workflow 10: RTA

Use this to query, enable, or disable RTA services.

  1. Confirm token and account ID.
  2. Use bilibili-mapi-rta.
  3. Common order:
    • Query available RTA groups.
    • Query available RTA IDs.
    • Query current binding status.
    • Enable or disable RTA.
    • Query binding status again to verify the result.

Workflow 11: One-Click Acceleration

Use this to enable or disable one-click acceleration for a unit.

  1. Confirm token and account ID.
  2. Query the unit with bilibili-mapi-unit-query.
  3. Query remaining unit budget if needed.
  4. Use bilibili-mapi-unit-accelerate to enable or disable one-click acceleration.
  5. Query unit status again to verify.

Workflow 12: Inefficient Unit Cleanup

Use this to query unit quota, scan rules, inefficient units, or custom cleanup rules.

  1. Confirm token and account ID.
  2. Use bilibili-mapi-batch-cleanup.
  3. Common order:
    • Query account unit quota.
    • Query account scan rules.
    • Query inefficient units.
    • Create a custom scan rule if needed.
  4. If inefficient units need to be paused or deleted in batch, switch to bilibili-mapi-batch-unit, then use bilibili-mapi-batch-status to query task results.

Known Gaps

  • Account qualification, brand qualification, brand information, and qualification package APIs currently do not have standalone skills. If creative creation requires qualification or brand-space fields, tell the user that the current skill set may be missing the relevant qualification endpoints.
  • Agency account opening, fund transfer, and ticket/work-order APIs are not included in this workflow.
  • Async reports, material analysis reports, and advertiser spend data reports do not have dedicated workflows here. The main reporting path currently uses custom reports.
  • The minimum required field combinations for specific industries, promotion goals, and creative templates should not be hardcoded in this workflow. Always return to campaign-save, unit-save, creative-save, and the metadata/resource references.

Response Habits

  • For query tasks: return account_id, date, measurement scope, key metrics, and whether pagination or empty data was involved.
  • For creation tasks: first summarize the campaign/unit/creative structure that will be created. Before write operations, confirm key fields and external impact.
  • For batch, delete, pause, close, or disable tasks: these have external impact. Confirm object IDs, object count, and operation type with the user before executing.
  • For failed responses: preserve the API's code, msg, error_code, and error_msg, and state which skill/reference endpoint failed.