拓冰网站定制 
Jellyfin API 快速上手指南从登录到控制播放的 6 个关键接口【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin你家里的 NAS 上存着几百部电影但想做一个自己的遥控器、写个脚本自动整理影库却没有入口Jellyfin API 就是这个入口登录拿到令牌后查媒体、管用户、上报播放进度全都用标准 HTTP 请求搞定。谁需要用到 Jellyfin API自建应用对接你写的小程序、桌面端、语音助手想直接摸到影库数据走 API 比爬网页稳定得多。自动化管理定时给新成员开账号、批量调整媒体库结构、脚本化备份用户数据一条 curl 就能干。扩展家庭媒体中心Jellyfin 的插件生态比如元数据插件本身就是通过接口体系运作的理解 API 就是理解它的扩展方式。第一次调用拿到你的令牌Jellyfin 的认证分三步用用户名密码登录 → 从响应里取出AccessToken→ 之后每个请求都带上它。登录接口由 UserController 提供POST /Users/AuthenticateByName Content-Type: application/json { Username: alice, Pw: MyPassw0rd! }登录成功后响应里最值钱的就是AccessToken和User.Id{ AccessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx, User: { Id: a1b2c3d4-e5f6-4a5b-9c8d-7e6f5a4b3c2d, Name: alice } }之后每次请求把令牌放进请求头即可GET /Items Authorization: MediaBrowser TokeneyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx整个调用过程画成时序图就是下面这样查询媒体资源按类型查电影和剧集查媒体库的主力是 ItemsController 的GET /Items。比如只看电影、一次取 10 条GET /Items?userIda1b2c3d4-e5f6-4a5b-9c8d-7e6f5a4b3c2dincludeItemTypesMovielimit10返回一个分页结构Items是数组TotalRecordCount是总数{ Items: [ { Id: b2c3d4e5-f6a7-5b6c-0d1e-8f9a0b1c2d3e, Name: 星际穿越, Type: Movie, PremiereDate: 2014-11-07T00:00:00Z, RunTimeTicks: 83700000000 } ], TotalRecordCount: 42 }几个最常用参数参数含义示例userId以哪个用户身份查询必填登录响应里的User.IdincludeItemTypes只查哪些类型逗号分隔可多选Movie、Series,Episode、Audiolimit本次最多返回几条25startIndex从第几条开始配合limit翻页25searchTerm按名称模糊搜索星际fields指定要返回的字段省流量Name, PremiereDate管理用户与媒体库创建用户管理员用POST /Users/New开新账号同样由 UserController 提供POST /Users/New Authorization: MediaBrowser Token... Content-Type: application/json { Name: bob, Password: Bob2026 }获取用户列表一条GET /Users带令牌就能拿到全部用户的Id、Name和角色方便脚本遍历。管理媒体库Jellyfin 用虚拟文件夹来定义媒体库——一个文件夹 一个collectionType就是一类库movies、tvshows、music、photos……。添加一个照片库的请求长这样路由定义见 LibraryStructureControllerPOST /Library/VirtualFolders?name家庭照片collectionTypephotosrefreshLibrarytrue Authorization: MediaBrowser Token... Content-Type: application/json { Locations: [/media/photos/family] }refreshLibrarytrue会让服务器立刻开始扫描不用等定时任务。控制播放上报进度与暂停恢复播放状态由 PlaystateController 负责。播放中每过几秒上报一次进度用POST /Sessions/Playing/ProgressPOST /Sessions/Playing/Progress Authorization: MediaBrowser Token... Content-Type: application/json { ItemId: b2c3d4e5-f6a7-5b6c-0d1e-8f9a0b1c2d3e, PositionTicks: 36000000000, IsPaused: false, MediaSourceId: 6f1e2d9a-3b4c-5d6e-7f80-91a2b3c4d5e6 }注意PositionTicks单位是1/10,000,000 秒——3600 秒就是36000000000。把IsPaused设为true就表示暂停客户端断开时再发一次Stopped接口收尾已看/未看状态就能在 Web 界面里正确显示。读懂错误码遇到 4xx 先查这张表状态码含义常见原因200成功—400请求参数错误缺了必填参数、类型写错401未认证令牌缺失、过期或请求头格式不对403权限不足普通用户调了管理员接口404资源不存在Id或路径打错500服务器内部错误服务端异常看服务器日志失败时响应体一般是这样的结构message里会有具体说明{ error: { code: Unauthorized, message: Invalid authentication token } }一个实用习惯看到 401 先检查请求头是不是MediaBrowser Token令牌的完整格式连引号都不能少而不是急着怀疑密码。让调用更优雅令牌存安全位置别硬编码写进配置文件或环境变量避免泄露进代码仓库令牌会过期失效后重新走一次登录即可。分页用startIndexlimit影库上千条很正常一次拉 100 条循环取比一次全量拉取对双方都友好。用fields过滤返回字段只想要名称和年份就传fieldsName,ProductionYear响应体积能小一大截。能批量就别循环同一类型的重复请求比如批量标记已看优先找带Ids或userId参数的聚合接口减少往返次数。升级前先跑一遍冒烟测试Jellyfin 迭代快大版本更新后对老接口做一轮回归能提前发现字段改名这类兼容性问题。到这里登录、查库、管人、报进度这套最小闭环就跑通了。剩下的 40 多个控制器都藏在 Jellyfin.Api/Controllers 目录里等你哪个功能痒了再去翻边用边学最省力。【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Jellyfin API 快速上手指南：从登录到控制播放的 6 个关键接口
Jellyfin API 快速上手指南从登录到控制播放的 6 个关键接口【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin你家里的 NAS 上存着几百部电影但想做一个自己的遥控器、写个脚本自动整理影库却没有入口Jellyfin API 就是这个入口登录拿到令牌后查媒体、管用户、上报播放进度全都用标准 HTTP 请求搞定。谁需要用到 Jellyfin API自建应用对接你写的小程序、桌面端、语音助手想直接摸到影库数据走 API 比爬网页稳定得多。自动化管理定时给新成员开账号、批量调整媒体库结构、脚本化备份用户数据一条 curl 就能干。扩展家庭媒体中心Jellyfin 的插件生态比如元数据插件本身就是通过接口体系运作的理解 API 就是理解它的扩展方式。第一次调用拿到你的令牌Jellyfin 的认证分三步用用户名密码登录 → 从响应里取出AccessToken→ 之后每个请求都带上它。登录接口由 UserController 提供POST /Users/AuthenticateByName Content-Type: application/json { Username: alice, Pw: MyPassw0rd! }登录成功后响应里最值钱的就是AccessToken和User.Id{ AccessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx, User: { Id: a1b2c3d4-e5f6-4a5b-9c8d-7e6f5a4b3c2d, Name: alice } }之后每次请求把令牌放进请求头即可GET /Items Authorization: MediaBrowser TokeneyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx整个调用过程画成时序图就是下面这样查询媒体资源按类型查电影和剧集查媒体库的主力是 ItemsController 的GET /Items。比如只看电影、一次取 10 条GET /Items?userIda1b2c3d4-e5f6-4a5b-9c8d-7e6f5a4b3c2dincludeItemTypesMovielimit10返回一个分页结构Items是数组TotalRecordCount是总数{ Items: [ { Id: b2c3d4e5-f6a7-5b6c-0d1e-8f9a0b1c2d3e, Name: 星际穿越, Type: Movie, PremiereDate: 2014-11-07T00:00:00Z, RunTimeTicks: 83700000000 } ], TotalRecordCount: 42 }几个最常用参数参数含义示例userId以哪个用户身份查询必填登录响应里的User.IdincludeItemTypes只查哪些类型逗号分隔可多选Movie、Series,Episode、Audiolimit本次最多返回几条25startIndex从第几条开始配合limit翻页25searchTerm按名称模糊搜索星际fields指定要返回的字段省流量Name, PremiereDate管理用户与媒体库创建用户管理员用POST /Users/New开新账号同样由 UserController 提供POST /Users/New Authorization: MediaBrowser Token... Content-Type: application/json { Name: bob, Password: Bob2026 }获取用户列表一条GET /Users带令牌就能拿到全部用户的Id、Name和角色方便脚本遍历。管理媒体库Jellyfin 用虚拟文件夹来定义媒体库——一个文件夹 一个collectionType就是一类库movies、tvshows、music、photos……。添加一个照片库的请求长这样路由定义见 LibraryStructureControllerPOST /Library/VirtualFolders?name家庭照片collectionTypephotosrefreshLibrarytrue Authorization: MediaBrowser Token... Content-Type: application/json { Locations: [/media/photos/family] }refreshLibrarytrue会让服务器立刻开始扫描不用等定时任务。控制播放上报进度与暂停恢复播放状态由 PlaystateController 负责。播放中每过几秒上报一次进度用POST /Sessions/Playing/ProgressPOST /Sessions/Playing/Progress Authorization: MediaBrowser Token... Content-Type: application/json { ItemId: b2c3d4e5-f6a7-5b6c-0d1e-8f9a0b1c2d3e, PositionTicks: 36000000000, IsPaused: false, MediaSourceId: 6f1e2d9a-3b4c-5d6e-7f80-91a2b3c4d5e6 }注意PositionTicks单位是1/10,000,000 秒——3600 秒就是36000000000。把IsPaused设为true就表示暂停客户端断开时再发一次Stopped接口收尾已看/未看状态就能在 Web 界面里正确显示。读懂错误码遇到 4xx 先查这张表状态码含义常见原因200成功—400请求参数错误缺了必填参数、类型写错401未认证令牌缺失、过期或请求头格式不对403权限不足普通用户调了管理员接口404资源不存在Id或路径打错500服务器内部错误服务端异常看服务器日志失败时响应体一般是这样的结构message里会有具体说明{ error: { code: Unauthorized, message: Invalid authentication token } }一个实用习惯看到 401 先检查请求头是不是MediaBrowser Token令牌的完整格式连引号都不能少而不是急着怀疑密码。让调用更优雅令牌存安全位置别硬编码写进配置文件或环境变量避免泄露进代码仓库令牌会过期失效后重新走一次登录即可。分页用startIndexlimit影库上千条很正常一次拉 100 条循环取比一次全量拉取对双方都友好。用fields过滤返回字段只想要名称和年份就传fieldsName,ProductionYear响应体积能小一大截。能批量就别循环同一类型的重复请求比如批量标记已看优先找带Ids或userId参数的聚合接口减少往返次数。升级前先跑一遍冒烟测试Jellyfin 迭代快大版本更新后对老接口做一轮回归能提前发现字段改名这类兼容性问题。到这里登录、查库、管人、报进度这套最小闭环就跑通了。剩下的 40 多个控制器都藏在 Jellyfin.Api/Controllers 目录里等你哪个功能痒了再去翻边用边学最省力。【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考