Bangumi API 文档

文档编号 03

03 - Bangumi API 文档研究笔记

日期：2026-04-28
用途：下一个项目功能开发参考
API 规范版本：2026-02-22（OAS 3.0.3）
文档地址：https://bangumi.github.io/api/
规范 JSON：https://bangumi.github.io/api/dist.json

认证方式

Authorization: Bearer <Access_Token>
  • Access Token 在 https://bgm.tv/dev 生成和管理
  • OptionalHTTPBearer：不传 token 也能访问（只读公开数据），有频率限制
  • HTTPBearer：强制登录，适用于写操作（收藏、进度更新等）
  • 注意：API Token 属于敏感凭证，不要提交到 Git，建议写入服务器环境变量

Base URL

https://api.bgm.tv

接口分组总览

条目（Subject）

方法路径说明需要 Token
GET/calendar每日放送可选
POST/v0/search/subjects条目搜索可选
GET/v0/subjects浏览条目可选
GET/v0/subjects/{subject_id}获取条目详情可选
GET/v0/subjects/{subject_id}/image获取条目图片（302重定向）可选
GET/v0/subjects/{subject_id}/persons关联人物可选
GET/v0/subjects/{subject_id}/characters关联角色可选
GET/v0/subjects/{subject_id}/subjects关联条目可选

条目图片 type 枚举：small / grid / large / medium / common

章节（Episode）

方法路径说明需要 Token
GET/v0/episodes获取章节列表（需传 subject_id）可选
GET/v0/episodes/{episode_id}获取章节详情可选

角色（Character）

方法路径说明需要 Token
POST/v0/search/characters角色搜索可选
GET/v0/characters/{character_id}角色详情可选
GET/v0/characters/{character_id}/image角色图片可选
GET/v0/characters/{character_id}/subjects角色相关条目可选
GET/v0/characters/{character_id}/persons角色相关人物（声优等）可选
POST/v0/characters/{character_id}/collect收藏角色必须
DELETE/v0/characters/{character_id}/collect取消收藏角色必须

人物（Person）

方法路径说明需要 Token
POST/v0/search/persons人物搜索可选
GET/v0/persons/{person_id}人物详情（60s 缓存）可选
GET/v0/persons/{person_id}/image人物图片可选
GET/v0/persons/{person_id}/subjects人物相关条目可选
GET/v0/persons/{person_id}/characters人物相关角色可选
POST/v0/persons/{person_id}/collect收藏人物必须
DELETE/v0/persons/{person_id}/collect取消收藏人物必须

用户（User）

方法路径说明需要 Token
GET/v0/me获取当前登录用户信息必须
GET/v0/users/{username}按用户名获取用户信息可选
GET/v0/users/{username}/avatar获取用户头像（302重定向）可选

收藏（Collection）

方法路径说明需要 Token
GET/v0/users/{username}/collections获取用户收藏列表可选（私有收藏需登录）
GET/v0/users/{username}/collections/{subject_id}获取用户单个条目收藏可选
POST/v0/users/-/collections/{subject_id}新增或修改条目收藏必须
PATCH/v0/users/-/collections/{subject_id}修改收藏（部分字段）必须
GET/v0/users/-/collections/{subject_id}/episodes章节收藏信息必须
PATCH/v0/users/-/collections/{subject_id}/episodes批量更新章节收藏必须
GET/v0/users/-/collections/-/episodes/{episode_id}单章节收藏信息必须
PUT/v0/users/-/collections/-/episodes/{episode_id}更新单章节收藏必须
GET/v0/users/{username}/collections/-/characters用户角色收藏列表可选

目录（Index）

方法路径说明需要 Token
GET/v0/indices/{index_id}目录详情可选
PUT/v0/indices/{index_id}编辑目录信息必须

关键枚举值

subject_type（条目类型）

值含义
1书籍
2动画
3音乐
4游戏
6三次元

collection type（收藏状态）

值动画/三次元书籍游戏
1想看想读想玩
2看过读过玩过
3在看在读在玩
4搁置搁置搁置
5抛弃抛弃抛弃

episode type（章节类型）

值含义
0本篇
1SP
2OP
3ED

常用请求示例

获取当前用户信息

GET https://api.bgm.tv/v0/me
Authorization: Bearer <token>

搜索动画条目

POST https://api.bgm.tv/v0/search/subjects
Authorization: Bearer <token>
Content-Type: application/json

{
  "keyword": "进击的巨人",
  "filter": {
    "type": [2]
  }
}

获取条目详情

GET https://api.bgm.tv/v0/subjects/253
Authorization: Bearer <token>

获取用户收藏列表（在看的动画）

GET https://api.bgm.tv/v0/users/{username}/collections?subject_type=2&type=3&limit=30&offset=0
Authorization: Bearer <token>

新增/更新条目收藏

POST https://api.bgm.tv/v0/users/-/collections/{subject_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": 3,
  "rate": 8,
  "comment": "很好看",
  "private": false
}

更新章节观看进度

PUT https://api.bgm.tv/v0/users/-/collections/-/episodes/{episode_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": 2
}

注意事项

  1. User-Agent：调用 API 时建议设置自定义 User-Agent，避免被限流
  2. 缓存：部分接口有服务端缓存（如 /v0/persons/{id} 60s 缓存）
  3. - 路径占位符：/v0/users/-/collections/... 中的 - 表示当前登录用户，只能配合 Token 使用
  4. 图片接口：返回 302 重定向到实际图片地址，需要跟随重定向
  5. 问题反馈：优先使用 GitHub Issue，不要在 bangumi 小组发帖