Bangumi API

Bangumi API Skill

This skill helps interact with the Bangumi (番组计划) API to query information about anime, manga, games, characters, persons, user collections, and broadcast calendar.

API Endpoint

Base URL: https://api.bgm.tv

Calendar URL: https://api.bgm.tv/calendar (no v0 prefix)

Authentication

Bangumi uses OAuth 2.0 with Authorization Code Grant flow for user authentication.

Getting a Token (Two Methods)

Method 1: Quick Access Token (Recommended for Testing)

1. Obtain a token from: https://next.bgm.tv/demo/access-token
2. Include in requests: Authorization: Bearer <your-token>

Method 2: Full OAuth 2.0 Flow (For Applications)

Step 1: Redirect user to authorization page

GET https://bgm.tv/oauth/authorize

Parameters:

Step 2: Exchange code for access token

POST https://bgm.tv/oauth/access_token

Parameters:

Response:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "expires_in": 604800,
  "token_type": "Bearer",
  "scope": null,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "user_id": USER_ID
}

Note: The code is valid for only 60 seconds!

Step 3: Use access token Include in requests: Authorization: Bearer <your-access-token>

Token Refresh

Use refresh token to get a new access token:

POST https://bgm.tv/oauth/access_token

Parameters:

Token Status Check

Check current token validity:

POST https://bgm.tv/oauth/token_status

Parameters:

Response:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "client_id": "YOUR_CLIENT_ID",
  "expires": 1520323182,
  "scope": null,
  "user_id": USER_ID
}

Auth Base URLs

• Authorization: https://bgm.tv/oauth/authorize
• Token: https://bgm.tv/oauth/access_token
• Token Status: https://bgm.tv/oauth/token_status
• API: https://api.bgm.tv

Rate Limits

• No explicit rate limit documented
• Recommended: 1 request per second

Available Endpoints

Public (No Auth Required)

Authenticated (GET)

Search (POST - Auth Required)

Search Filter Options

Search Query Parameters:

Filter Conditions (all are AND relationships):

Example with filters:

{
  "keyword": "Clannad",
  "sort": "rank",
  "filter": {
    "type": [2],
    "rating": {"min": 8},
    "tag": ["治愈"]
  }
}

More API Endpoints

Index Endpoints (New in v0)

Query parameters: limit, offset

User Collections

Collection query parameters:

Subject Types

Shell Script Usage

A lightweight curl-based script is provided at scripts/bangumi_query.sh:

Quick Commands

# Get broadcast calendar
./scripts/bangumi_query.sh calendar

# Search subjects (anime)
./scripts/bangumi_query.sh search_subjects "Clannad"

# Search characters
./scripts/bangumi_query.sh search_characters "Higurashi"

# Search persons
./scripts/bangumi_query.sh search_persons "Miyazaki"

# Get subject by ID
./scripts/bangumi_query.sh subject 100228

# Get subject characters
./scripts/bangumi_query.sh characters 100228

# Get subject persons
./scripts/bangumi_query.sh persons 100228

# Get person by ID
./scripts/bangumi_query.sh person 1

# Get character by ID
./scripts/bangumi_query.sh character 1

# Get current user info (requires auth)
./scripts/bangumi_query.sh me

# Get user collections
./scripts/bangumi_query.sh collections "username"

# Browse subjects by type
./scripts/bangumi_query.sh subjects 2 10

Advanced Usage

# Set token
export BGM_TOKEN="your-token"

# Search with filter
./scripts/bangumi_query.sh search_subjects "Clannad" "score"

# Get user collections with status
./scripts/bangumi_query.sh collections "username" "doing"

Available Commands

curl Example Requests

Get Calendar

curl https://api.bgm.tv/calendar \
  --header 'Accept: application/json'

Search Subjects

curl -X POST https://api.bgm.tv/v0/search/subjects \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{"keyword": "Clannad"}'

Search with Filter

curl -X POST https://api.bgm.tv/v0/search/subjects \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
    "keyword": "Clannad",
    "sort": "rank",
    "filter": {"type": [2]}
  }'

Get Subject by ID

curl https://api.bgm.tv/v0/subjects/100228 \
  --header 'Authorization: Bearer <token>'

Get Subject Characters

curl https://api.bgm.tv/v0/subjects/100228/characters \
  --header 'Authorization: Bearer <token>'

Get Subject Persons

curl https://api.bgm.tv/v0/subjects/100228/persons \
  --header 'Authorization: Bearer <token>'

Get User Info

curl https://api.bgm.tv/v0/users/540730 \
  --header 'Authorization: Bearer <token>'

Get Current User

curl https://api.bgm.tv/v0/me \
  --header 'Authorization: Bearer <token>'

Get User Collections

curl "https://api.bgm.tv/v0/users/540730/collections?limit=10" \
  --header 'Authorization: Bearer <token>'

Response Format

Subject

{
  "id": 100228,
  "name": "ラジオCD「中二病でも恋がしたい!~闇の炎に抱かれて聴け~」 Vol.6",
  "name_cn": "",
  "type": 3,
  "summary": "...",
  "rating": {"score": 9, "total": 2},
  "collection": {"collect": 2, "wish": 0, "doing": 0, "on_hold": 0, "dropped": 1}
}

Search Result

{
  "total": 68,
  "data": [
    {"id": 13, "name": "CLANNAD", "name_cn": ""}
  ]
}

Calendar

[
  {
    "weekday": {"en": "Mon", "cn": "星期一", "ja": "月耀日", "id": 1},
    "items": [...]
  }
]

Error Codes

Tips

• Calendar endpoint uses /calendar (no v0 prefix)
• Search endpoints require POST with JSON body
• Use type parameter to filter subjects by type (1=book, 2=anime, 3=music, 4=game, 6=real)
• Subject IDs are integers, not strings
• User identifiers can be username (string) or user ID (integer)

Reference Documentation

For complete API documentation, see references/api_docs.md in this skill folder.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.