bilibili-hub

Modified from: jackwener/bilibili-cli (Apache-2.0)

This skill simplifies and modifies the original repository as follows:

• Removed the browser-cookie3 / click / rich / PyYAML / qrcode dependencies
• Changed cookie authentication to accept a dict directly or read from environment variables, without automatic browser extraction
• Removed the CLI layer (commands/), QR login, formatters, and related components
• Kept all API methods and wrapped them uniformly as synchronous interfaces (asyncio.run)
• Core dependency: bilibili-api-python, a third-party SDK that reverse engineers the Bilibili API
• In the Minis environment, cookies are obtained automatically through browser_use get_cookies

File Structure

/var/minis/skills/bilibili-hub/
├── SKILL.md
├── pyproject.toml          # bilibili-api-python + aiohttp
└── scripts/
    ├── __init__.py
    ├── exceptions.py       # 6 structured exception types
    ├── payloads.py         # Data structure normalization (normalize_* functions)
    └── client.py           # BiliClient core class (all API methods)

Authentication Methods

The Bilibili Web API uses three key cookies:

Method 1: Automatically retrieve via browser_use (preferred in Minis environments)

1. Use browser_use navigate to open https://www.bilibili.com and confirm that you are logged in.
2. Use browser_use get_cookies to retrieve cookies (raw values do not appear in the conversation).
3. Load the offload env file:

. /var/minis/offloads/env_cookies_www_bilibili_com_xxx.sh
export BILI_SESSDATA="$COOKIE_SESSDATA"
export BILI_JCT="$COOKIE_BILI_JCT"
export BILI_USERID="$COOKIE_DEDEUSERID"
export BILI_BUVID3="$COOKIE_BUVID3"

Note: get_cookies only applies to the current page's domain. Navigate to https://www.bilibili.com before calling it.

Method 2: Manually retrieve from browser DevTools

1. Log in to Bilibili, then open DevTools -> Application -> Cookies -> https://www.bilibili.com.
2. Find the values of SESSDATA, bili_jct, and DedeUserID.
3. Store them in the Minis environment variables: BILI_SESSDATA / BILI_JCT / BILI_USERID.

Ways to pass cookies (three methods)

# Method 1: From environment variables (recommended)
client = BiliClient.from_env()

# Method 2: Pass a dict directly
client = BiliClient({
    "SESSDATA":   os.environ["BILI_SESSDATA"],
    "bili_jct":   os.environ["BILI_JCT"],
    "DedeUserID": os.environ["BILI_USERID"],
})

# Method 3: Read-only operations (no write permissions required)
client = BiliClient({"SESSDATA": os.environ["BILI_SESSDATA"]})

Quick Start

Environment setup

cd /var/minis/skills/bilibili-hub
uv sync

Calling as a Python library

import os, json, sys
sys.path.insert(0, "/var/minis/skills/bilibili-hub")
from scripts.client import BiliClient

client = BiliClient.from_env()

# Current user information
me = client.whoami()
print("User:", me.get("name"), "UID:", me.get("mid"))

# Search videos
videos = client.search_videos("Python Tutorial", count=5)
for v in videos:
    print(f"  {v['bvid']} {v['title']} ({v['duration']})")

# Get video details (including subtitles)
detail = client.get_video("BV1xx411c7mD", subtitle=True)
print(detail["video"]["title"])
print(detail["subtitle"]["text"][:200])

# Popular videos
hot = client.get_hot(count=10)
for v in hot:
    print(f"  {v['bvid']} {v['title']} 👁{v['stats']['view']}")

API Method Quick Reference

Account

Video

bvid supports a BV number or full URL and is extracted automatically.

Users

Search

Discover

Favorites / History

Download

Download process:

• DASH streams (common): download the video stream and audio stream separately -> merge with ffmpeg copy -> if merging fails, keep the silent video
• FLV/MP4 streams (rare): download directly, no merging required
• Without logging in, downloads are limited to 480P; after logging in, 1080P is available (premium members can download higher quality)

Error Handling

from scripts.exceptions import (
    AuthenticationError,  # Cookie missing or expired
    RateLimitError,       # Triggered risk control (412)
    NotFoundError,        # Video/user does not exist
    NetworkError,         # Network/timeout error
    InvalidBvidError,     # Invalid BV number format
    BiliError,            # Other API error (base class)
)

try:
    detail = client.get_video("BV1xx411c7mD")
except AuthenticationError:
    print("Cookie has expired. Please retrieve it again.")
except RateLimitError:
    print("Risk control triggered. Try again later.")
except NotFoundError:
    print("Video does not exist.")
except BiliError as e:
    print(f"API error: {e}")

Important Notes

• SESSDATA is the minimum requirement for read operations. Write operations (likes, coins, posting dynamics) also require bili_jct.
• Cookies are usually valid for several days to several weeks. After they expire, retrieve them again through browser_use get_cookies.
• Bilibili applies risk control to high-frequency requests (HTTP 412). An operation interval of at least 1 second is recommended.
• bilibili-api-python is a community-maintained reverse-engineering project, and its interfaces may break when Bilibili updates.
• Write operations (coins, triple action, etc.) cannot be reversed. Use them with caution.