/bilibili-api

name: bilibili-api
description: This skill should be used when the user asks to "use bilibili API", "download bilibili video", "get bilibili user info", "list bilibili favorites", "send bilibili danmaku", "upload video to bilibili", "monitor bilibili live room", "search bilibili", "get bilibili comments", or needs guidance on the bilibili_api Python library usage, authentication, API endpoints, or workflow patterns.
version: 0.1.0

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