archibate/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
)

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