Bilibili Sanlian Ads — Material Management (素材管理)

Getting images and videos into an advertiser account, tagging them, and pushing them to other accounts. Once material exists here, bilibili-sanlian-ads-metadata is what reports it as deliverable, and the ad skills are what attach it to an ad.

Usage Rules

Confirm a valid access_token and advertiser account_id first; use bilibili-sanlian-ads when either is missing.
Every MAPI call goes through scripts/mapi.sh (on Windows use py -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-write curl, requests or fetch for a MAPI call, and never fan out across accounts or objects in parallel.
Exception — the pre-signed video upload is not a MAPI call. PUT the file directly to the pre-signed URL with an ordinary HTTP client, not through the client: it must carry neither the Bearer token nor X-Call-Source.
Base domain https://cm.bilibili.com/takumi/api; Authorization: Bearer {access_token}; JSON bodies need Content-Type: application/json; every MAPI request needs X-Call-Source: sanlian-skills and X-Sanlian-Skills-Version: 3.0.4.
Open the matching reference before composing any request. Format, dimension, size and duration constraints are specified per endpoint and are enforced — do not guess them, and do not assume an image spec carries over to video.
Follow the sequential-call and error-stop discipline in bilibili-sanlian-ads. Upload or transfer one item at a time, and do not start the next request until the previous one has completed and its response has been checked.
Follow the main skill's operation brief, staged confirmation, canary and run-journal rules for uploads, deletes, tag writes and cross-account pushes. For multiple files or targets, verify one canary before asking to continue.
Uploading is not idempotent. A retry after an unclear failure can create a duplicate material — check whether the first attempt landed before retrying.
Deleting an image or a tag can affect ads already using it. Confirm with the user before any delete.

When To Use

| Goal | Reference | |---|---| | Upload an image from a file or from a URL, list images, delete an image | references/1890_图片管理.md | | Upload a video file, create archives from it, track processing, find postable UP MIDs | references/1889_视频管理.md | | Create, list, update, delete material tags and bind them to materials | references/1891_素材标签管理.md | | Push a material to other advertiser accounts | references/1960_素材推送.md |

Video Upload Is Two Systems, Not One

This trips up almost every new integration. Uploading a video file is not a MAPI call:

Call MAPI to get a pre-signed URL (…/meta_data/signed_urls). This is a MAPI request and needs the Bearer token.
PUT the video file directly to that pre-signed URL. This is an ordinary external HTTP request — not MAPI. It does not use the Bearer token, does not need X-Call-Source, and does not count against MAPI quota. Sending the Bearer token here can cause the upload to be rejected.
Call MAPI to create archives from the uploaded file (…/meta_data/create/archives), in bulk.
Poll processing progress — either by processing ID (…/archive/progress) or by file MD5 (…/archive/v1/progress). Video processing is asynchronous and takes real time; poll with backoff, not in a tight loop. Local preparation may continue, but do not start another MAPI sequence or submit another asynchronous MAPI job until this item reaches terminal status and its result is checked.

An archive can belong to the advertiser account directly, or be posted under an UP owner's mid once that creator has completed delivery authorization. Use …/meta_data/enterprise/mid to find which MIDs the account may post to; authorization itself is handled in bilibili-sanlian-ads-assets.

Keep the file MD5 you computed. It is how you look up progress without a processing ID, and in creative-driven delivery 2.0 it is what registers a local video as a media_id (cm_video.file_md5).

Images

Two upload paths — by file and by URL (upload_pic and upload_pic_with_url). Prefer the URL path when the image is already hosted; it avoids a multipart transfer. Both are subject to the same format and dimension constraints, which vary by intended placement, so resolve the creative placement first when the image is destined for a specific slot.

…/meta_data/launch/medias lists existing images. Check it before uploading — re-uploading an image the account already has creates a duplicate rather than deduplicating.

Material Tags

Tags are an organizational layer over materials, useful for large accounts. The endpoints cover paged tag listing, batch insert, single manage, update, delete, binding tags to materials, and listing materials under a tag. Tag binding accepts archives, local videos and dynamics, and the reference points at the same lookup endpoints used in bilibili-sanlian-ads-metadata for resolving those materials.

Deleting a tag unbinds it everywhere. Confirm before doing it.

Material Push

…/meta_data/v3/file/material/bind pushes a material to other advertiser accounts, so several accounts can use the same asset without re-uploading. Because this writes into accounts other than the one you are working in, confirm the target account list with the user explicitly and never expand it beyond what they named.

Feeding The Two Delivery Structures

Legacy: material is referenced directly in the creative save request. See bilibili-sanlian-ads-ad-management.
Creative-driven 2.0: material must first become a globally unique media_id. Images register with image.url; local videos register with cm_video.file_md5 — the MD5 from the video upload above. See bilibili-sanlian-ads-delivery.

Reading Responses And Errors

Business success or failure is carried in the response body, not the HTTP status. Bulk endpoints report per-item outcomes — iterate them; a successful envelope does not mean every item was accepted.

The pre-signed URL step is outside MAPI, so its failures look completely different: they are storage-service HTTP errors, not MAPI envelopes. Diagnose them as ordinary HTTP problems (expired URL, wrong method, content-length mismatch), and if the URL has expired, request a fresh one rather than retrying the old one.

On any MAPI error, timeout, partial item result or unclear outcome, stop and run the main skill's cold re-check and support-packet workflow. Do not retry with altered fields to discover what the API wants.

Source Document Index

Synced from mapi/product/docs/开发者中心/MAPI接入/素材管理/. doc_id matches the article ID on the developer site.

| Source document | Local reference | Endpoints | |---|---|---| | 图片管理 (1890) | references/1890_图片管理.md | …/v3/creative/upload_pic, …/v3/creative/upload_pic_with_url, …/launch/medias, …/v3/file/image/delete | | 视频管理 (1889) | references/1889_视频管理.md | …/signed_urls, external PUT to the signed URL, …/create/archives, …/archive/progress, …/archive/v1/progress, …/enterprise/mid | | 素材标签管理 (1891) | references/1891_素材标签管理.md | …/v3/resource/material_tag/ list/page, batch_insert, single_manage, update, delete, bind, list_material | | 素材推送 (1960) | references/1960_素材推送.md | …/v3/file/material/bind |