bilibili-api Skill

Overview

bilibili-api (package: bilibili-api-python, v17.4.1) is a comprehensive async Python wrapper for Bilibili's APIs with 400+ endpoints across 42 modules. All operations are async (asyncio-based) with a sync wrapper available. Supports three HTTP backends: curl_cffi, aiohttp, httpx.

• Source code: <project_root>/bilibili_api/
• Documentation (Chinese): references/docs/
• Module API docs: references/docs/modules/*.md
• Usage examples: references/docs/examples/*.md

Quick Start

Install the library and at least one HTTP backend:

uv pip install bilibili-api-python aiohttp
# or: uv pip install bilibili-api-python curl_cffi
# or: uv pip install bilibili-api-python httpx

Minimal example (anonymous, no credentials needed):

import asyncio
from bilibili_api import video

async def main():
    v = video.Video(bvid="BV1uv411q7Mv")
    info = await v.get_info()
    print(info["title"], info["stat"]["view"])

asyncio.run(main())

Or use the sync wrapper:

from bilibili_api import video, sync

v = video.Video(bvid="BV1uv411q7Mv")
info = sync(v.get_info())
print(info["title"])

See scripts/quickstart.py for a runnable example.

Credential Setup

Most read operations work without credentials. Write operations (like, comment, upload) and some read operations (user history, favorites) require authentication via the Credential class.

from bilibili_api import Credential

credential = Credential(
    sessdata="...",       # Required for GET (read) operations
    bili_jct="...",       # Required for POST (write) operations
    buvid3="...",         # Device ID (auto-generated if omitted)
    buvid4="...",         # Device ID v4 (optional)
    dedeuserid="...",     # User ID (rarely needed)
    ac_time_value="...",  # For cookie refresh only
)

Extract from browser: Open bilibili.com > F12 DevTools > Application (Chrome) or Storage (Firefox) > Cookies > .bilibili.com > copy SESSDATA, bili_jct, buvid3.

Programmatic login: Use login_v2 module for QR code, password, or SMS login.

Cookie refresh: Use credential.check_refresh() and credential.refresh() when cookies expire.

For complete details, consult references/credential-setup.md. To validate credentials, run scripts/credential_check.py.

Key Modules

Category	Module	Description	Key Class
Content	video	Video info, actions, danmaku, download	Video
	bangumi	Anime/drama series	Bangumi
	article	Column articles	Article
	audio	Audio tracks	Audio
	manga	Manga/comics	Manga
	cheese	Paid courses	CheeseList, CheeseVideo
	opus	Image posts	Opus
	note	Notes	Note
Social	user	User profiles, followers, videos	User
	dynamic	User dynamics/feeds	Dynamic
	comment	Comments on any resource	Comment
	session	Private messages	(functions)
	emoji	Emoji/sticker packs	(functions)
Discovery	search	Search videos/users/articles	(functions)
	hot	Trending content	(functions)
	rank	Rankings	(functions)
	homepage	Homepage recommendations	(functions)
	video_zone	Video category zones	(functions)
Live	live	Live rooms, danmaku, gifts	LiveRoom, LiveDanmaku
	live_area	Live streaming categories	(functions)
Upload	video_uploader	Video upload workflow	VideoUploader
	audio_uploader	Audio upload workflow	AudioUploader
Account	login_v2	Login (QR/password/SMS)	QrCodeLogin
	creative_center	Creator dashboard	(functions)
	favorite_list	Favorites management	FavoriteList

For the complete list of all 42 modules with classes and methods, consult references/api-modules.md.

Core Patterns

Async Usage

All API methods are async. Standard pattern:

import asyncio
from bilibili_api import video, Credential

async def main():
    cred = Credential(sessdata="...", bili_jct="...")
    v = video.Video(bvid="BVxxxxxxxx", credential=cred)
    info = await v.get_info()
    await v.like(True)

asyncio.run(main())

Sync Wrapper

For scripts that don't need async:

from bilibili_api import sync
result = sync(v.get_info())

Note: sync() cannot be called inside an already-running event loop.

Error Handling

from bilibili_api import ResponseCodeException, NetworkException

try:
    info = await v.get_info()
except ResponseCodeException as e:
    print(f"API error {e.code}: {e.msg}")  # Bilibili API returned error
except NetworkException as e:
    print(f"HTTP error {e.status}: {e.msg}")  # Network/HTTP failure

Key exceptions: ResponseCodeException (API error code), NetworkException (HTTP error), ArgsException (bad parameters), CredentialNo*Exception (missing auth fields).

Event System (WebSocket)

Used by LiveDanmaku, VideoOnlineMonitor, uploaders:

from bilibili_api import live

room = live.LiveDanmaku(room_display_id=123456)

@room.on("DANMU_MSG")
async def on_danmaku(event):
    print(event["data"]["info"][1])  # danmaku text

await room.connect()

ID Conversion

from bilibili_api import aid2bvid, bvid2aid
bvid = aid2bvid(170001)        # -> "BV17x411w7KC"
aid = bvid2aid("BV17x411w7KC") # -> 170001

Link Parsing

from bilibili_api import parse_link, get_real_url
# Resolve b23.tv short URLs
real_url = await get_real_url("https://b23.tv/xxxxxxx")
# Parse any bilibili link to resource type + ID
resource = await parse_link(real_url)

For detailed patterns (download, danmaku, pagination, Picture class), consult references/common-patterns.md.

Configuration

from bilibili_api import request_settings, request_log, select_client

# Proxy
request_settings.set_proxy("http://127.0.0.1:7890")

# Timeout (default: 30s)
request_settings.set_timeout(60.0)

# Switch HTTP backend
select_client("curl_cffi")  # or "aiohttp", "httpx"

# Enable request logging
request_log.set_on(True)

# Anti-spider (usually automatic)
from bilibili_api import recalculate_wbi, refresh_buvid
await recalculate_wbi()  # Force WBI key refresh
await refresh_buvid()    # Force buvid refresh

For full configuration details, consult references/configuration.md.

Reference Files

Detailed References

File	Description
references/credential-setup.md	Complete credential guide: browser extraction, programmatic login (QR/password/SMS), cookie refresh
references/api-modules.md	All 42 modules with classes, key methods, and auth requirements
references/configuration.md	Request settings, proxy, HTTP clients, logging, anti-spider measures
references/common-patterns.md	Async/sync patterns, error handling, events, danmaku, download, pagination
references/video-guide.md	Video module deep dive: info, actions, danmaku, download with quality selection
references/user-guide.md	User module deep dive: profile, content listing, social actions, pagination
references/live-guide.md	Live module deep dive: room info, WebSocket danmaku, gift tracking
references/upload-guide.md	Video/audio upload workflows with event monitoring
references/self-update.md	Skill self-update workflow: check for new releases, sync docs, update version info

Utility Scripts

File	Description
scripts/quickstart.py	Minimal runnable example (anonymous video info retrieval)
scripts/credential_check.py	Validate credentials from environment variables

Source Documentation

For exhaustive API signatures, consult the project's built-in docs:

• Module API reference: references/docs/modules/<module>.md
• Usage examples: references/docs/examples/<module>.md