Jellyfin API 实战指南从认证到查库的 4 个场景【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin想在自己的 App 或小脚本里接一个家庭影音库Jellyfin 服务器把所有能力都开放成了 Jellyfin API认证、查库、用户管理、播放进度上报全都能通过 HTTP 请求完成。本文按你要做的事来组织四个场景走一遍请求可以直接复制去试。第一步拿到 Jellyfin 认证令牌Jellyfin 用令牌换权限的方式保护接口。整个认证过程是这样的你向POST /Users/AuthenticateByName发送用户名和密码服务器校验通过创建会话返回AccessToken之后的每个请求都带上请求头Authorization: MediaBrowser Token令牌令牌失效时服务器返回 401重新走第 1 步换新令牌即可认证入口在 UserController 中POST /Users/AuthenticateByName Content-Type: application/json { Username: admin, Pw: your_password }成功后响应里最有用的是这两段{ AccessToken: eyJhbGciOi..., User: { Id: 8f2c1a, Name: admin } }记住AccessToken和User.Id后面所有场景都用得到。场景一 查询你的电影列表需求一句话列出媒体库里的电影一次看 20 部。这是 ItemsController 提供的 Jellyfin 查询接口GET /Items?userId8f2c1aincludeItemTypesMovielimit20 Authorization: MediaBrowser TokeneyJhbGciOi...响应是一个包裹在Items数组里的对象列表每部影片带Id、Name、Type、PremiereDate、RunTimeTicks等字段TotalRecordCount告诉你总共还有多少条没取完就带着startIndex继续翻。常用参数userId必填用谁的权限查结果按该用户的访问范围过滤includeItemTypes逗号分隔如Movie,Serieslimit/startIndex分页fields只要指定字段响应更小场景二Jellyfin 用户管理——新建一个账户需求一句话给家人开个账号只让他看自己想看的。创建用户是管理员操作用管理员令牌请求POST /Users/New Authorization: MediaBrowser TokeneyJhbGciOi... Content-Type: application/json { Name: new_user, Password: strong_password }创建成功后用GET /Users随时列出全部用户响应数组里每个用户都有Id、Name、Policy权限项。如果拿到 403说明你当前令牌不是管理员换管理员账号重新认证。场景三Jellyfin 播放进度上报需求一句话播放器播到一半让服务器知道看到第 1 小时了。进度接口在 PlaystateController 中格式如下POST /PlayingItems/3b9d2f/Progress Authorization: MediaBrowser TokeneyJhbGciOi... Content-Type: application/json { PositionTicks: 36000000000, DeviceId: my-app-001, IsPaused: false }响应是 204无正文。上报之后服务器会更新该项的继续观看状态客户端首页的续播卡片、播放过的标记都靠它驱动。PositionTicks单位是 100 纳秒1 小时正好是 36000000000。场景四新增一个 Jellyfin 媒体库需求一句话把/media/photos/family挂进来当照片库。建库走POST /Library/VirtualFolders实现见 LibraryStructureControllerPOST /Library/VirtualFolders Authorization: MediaBrowser TokeneyJhbGciOi... Content-Type: application/json { Name: Family Photos, CollectionType: photos, Locations: [/media/photos/family], RefreshLibrary: true }CollectionType常见取值movies、tvshows、music、photos、books。RefreshLibrary设为true时建完立即开始扫描不用手动触发。排错速查按状态码对照状态码含义常见原因200成功—400参数错误userId缺失、JSON 格式不对401认证失败令牌过期、拼错请求头403权限不足非管理员调了管理接口404资源不存在itemId写错或项目已被移除500服务器错误看服务器日志定位401 的响应体长这样单行 JSON{ErrorType:Unauthorized,ErrorMessage:Invalid token.}。看到ErrorType就能快速判断类别不必逐条猜。避坑清单五件事记一下令牌当密码保管——写进环境变量或配置别提交进代码仓库永远分页——大数据集务必带limit和startIndex否则一次拉爆内存用fields瘦身——只取Name,Overview这类需要的字段传输量差几倍进度按间隔上报——建议 10 秒一次别每一帧都打一次接口能合的请求就合——用parentItemIds、过滤参数一次取齐减少往返次数收尾Jellyfin API 的完整端点列表可以直接看服务器自带的 OpenAPI 页面/index.html遇到问题也可以去官方社区发帖提问。把认证跑通之后剩下的就是照着这四个场景往上加功能。【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
