Bangumi Server 条目 API 深度解析：5 大类型与筛选条件进阶玩法

Bangumi Server 条目 API 深度解析5 大类型与筛选条件进阶玩法【免费下载链接】serverAPI server for bgm.tv项目地址: https://gitcode.com/gh_mirrors/server17/serverBangumi Server 条目 API 是 bgm.tvBangumi 番组计划官方开源后端提供的核心接口。无论你是想构建追番提醒工具、动漫资料站还是个人收藏管理应用掌握这套条目 API 的 5 大类型与筛选条件都能让你轻松获取动画、书籍、音乐、游戏等海量条目数据。本文基于 openapi/v0.yaml 官方接口定义从零带你吃透条目 API 的使用姿势。什么是 Bangumi ServerBangumi Server 是 bgm.tv 的开源后端服务器采用 Go 语言编写基于 Echo Web 框架与 GORM 数据库框架构建对外提供一套/v0/版本的 RESTful API。条目Subject是这套 API 中最核心的数据模型涵盖了动画、漫画、小说、音乐、游戏、三次元影视等一切可以被收藏和评价的对象。想本地运行这套服务可以这样初始化git clone --recursive https://gitcode.com/gh_mirrors/server17/server bangumi-server cd bangumi-server task启动 HTTP 服务则使用task web相关配置项可参考 config.example.toml 与 config/config.go。条目 API 的 5 大类型一张表看懂 Bangumi 的条目类型由SubjectType枚举定义在源码 internal/model/subject_type.go 和 openapi/components/subject_type.yaml 中可以找到完整定义类型值英文名中文名说明1Book书籍漫画、小说、画集、写真等2Anime动画日本动画、国产动画等3Music音乐专辑、单曲、原声带4Game游戏主机、PC、掌机游戏6Real三次元真人影视剧、综艺等⚠️ 注意一个小细节类型枚举里没有 5从 4 直接跳到 6调用时传 5 会返回 400 错误。这个坑在官方 schema 中专门标注过。条目 API 数据结构一次请求拿到全部信息 通过GET /v0/subjects/{subject_id}获取单个条目时返回的 JSON 结构非常丰富核心字段定义在 openapi/components/subject_v0.yaml基础信息id、name日文/原文名、name_cn中文名、summary简介、date播出/发售日期类型与平台type、platform如 TV、Web、欧美剧、series是否为书籍系列主条目图片资源images提供 small / grid / large / medium 多种尺寸封面评分体系rating内含rank排名、score评分、total总分以及 1~10 星的count分布收藏统计collection给出wish想看、collect看过、doing在看、on_hold搁置、dropped抛弃五类人数标签信息tags为普通用户标签meta_tags为维基人维护的公共标签对应处理逻辑见 web/handler/subject/get.go缓存策略是 300 秒。最常用的 5 个条目 API 端点 条目相关的 RESTful 端点全部注册在 web/handler/subject/subject.go 的Routes方法中端点作用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获取关联角色其中人物与角色端点还支持通过type参数筛选例如只取原作或主角非常适合搭建角色百科类应用。浏览条目筛选条件年份、月份、分类进阶玩法 GET /v0/subjects是最灵活的浏览接口参数解析逻辑位于 web/handler/subject/browse.gotype必填指定 5 大条目类型之一cat条目分类仅对书籍/游戏有效例如书籍的 1001 为漫画、1002 为小说游戏可指定平台分类series是否系列仅对书籍生效platform平台筛选仅对游戏生效sort排序方式支持date按日期和rank按排名year/month按播出/发售年份、月份筛选年份范围限制在 1900~3000 之间 实战技巧想获取 2023 年 7 月新番动画只需请求GET /v0/subjects?type2year2023month7sortrank配合limit/offset分页参数就能轻松实现新番时间表功能。第一个分页响应会被缓存 24 小时之后缓存 1 小时注意合理利用。搜索条目筛选条件标签、评分、排名的组合玩法 POST /v0/search/subjects是实验性的高级搜索接口底层基于 Meilisearch 全文检索引擎实现代码在 internal/search/subject/handle.go入口见 web/handler/search.go。请求体需要keyword并支持强大的filter对象筛选字段说明示例type条目类型多值之间为或关系[2, 4]同时搜动画和游戏tag/meta_tags标签多值之间为且关系-前缀可排除[童年, -科幻]air_date播出/发售日期支持、等比较符[2020-07-01, 2020-10-01]rating评分区间筛选[6, 8]rating_count按评分人数筛选[200, 5000]rank按 Bangumi 排名筛选[10, 18]nsfw是否包含 R18 内容true/false同时可通过sort指定排序match匹配度默认、heat收藏热度、rank排名、score评分。 实战技巧想找出评分 8 分以上、2021 年之后发售、被 1000 人以上评分的高分游戏可以这样构造请求体POST /v0/search/subjects { keyword: 游戏名, sort: score, filter: { type: [4], rating: [8], rating_count: [1000], air_date: [2021-01-01] } }结语 ✨Bangumi Server 条目 API 的设计兼顾了简单浏览与深度检索两种场景GET /v0/subjects适合快速拉取某类型条目列表POST /v0/search/subjects则适合做精细化筛选。配合 5 大条目类型、丰富的评分/收藏字段与分页缓存机制足以支撑起绝大多数二次元数据类应用的开发需求。后续你还可以深入研究 openapi/v0.yaml 中的章节Episodes、角色、人物、收藏等接口把条目 API 与它们串联起来构建更完整的 Bangumi 数据应用。【免费下载链接】serverAPI server for bgm.tv项目地址: https://gitcode.com/gh_mirrors/server17/server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考