Bilibili API

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
)

Local convention — check first: This machine stores credentials at ~/.config/bilibili.env (chmod 600).

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

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

Utility Scripts

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