Jellyfin API 实战教程4 个关卡搞定认证、查询与数据写入【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin你想给家庭影院做个遥控 App或者写个脚本每天自动检查媒体库有没有新片入库只要 Jellyfin一个可自托管的开源媒体服务器跑在你的机器上这些事情都能通过它的 HTTP 接口——也就是Jellyfin API——完成。本文不讲抽象架构按动手闯关的顺序带你走完先拿到访问令牌再查一遍媒体库然后试着写入数据最后备一份排错速查。跟着做你就能把自己的 App 或脚本接进 Jellyfin。 第一关拿到 Jellyfin 认证令牌登录接口写法Jellyfin 的多数接口要求先登录换一张令牌。登录接口是POST /Users/AuthenticateByName把用户名和密码放在 JSON 请求体里curl -X POST http://127.0.0.1:8096/Users/AuthenticateByName \ -H Content-Type: application/json \ -d {Username: admin, Pw: 你的密码}响应里重点看两个字段{ AccessToken: a1b2c3d4e5f6g7h8i9j0, User: { Id: 3f2a8b9c-1d2e-4a3b-9c8d-0e1f2a3b4c5d, Name: admin }, SessionInfo: { Id: 6e5d4c3b-... } }AccessToken你的访问令牌后面每个请求都要带上User.Id用户 ID查询媒体库等接口要用到先存下来。拿到令牌后放进请求头的X-Emby-Token即可也可以写成Authorization: MediaBrowser Token...的形式二者等价curl http://127.0.0.1:8096/Users/Me \ -H X-Emby-Token: a1b2c3d4e5f6g7h8i9j0如果返回了你自己的用户信息说明令牌生效了第一关通过。想确认令牌是否还有效随时可以打这个GET /Users/Me。 第二关查询媒体库Jellyfin 接口调用示例现在用一次真实查询把类型过滤、分页、字段裁剪这些常用参数一次串起来。请求GET /Items带上上一关存下的用户 IDcurl http://127.0.0.1:8096/Items?userId3f2a8b9c-...includeItemTypesMovieRecursivetrueSortByPremiereDateSortOrderDescendingStartIndex0Limit20fieldsPrimaryImageAspectRatio \ -H X-Emby-Token: a1b2c3d4e5f6g7h8i9j0各参数在做什么includeItemTypesMovie只查电影换成Series、MusicAlbum或逗号分隔的多个类型也行Recursivetrue递归进入子文件夹StartIndex0Limit20分页第一页 20 条下一页把StartIndex改成 20fieldsPrimaryImageAspectRatio字段裁剪只额外返回你点名的字段省流量SortByPremiereDateSortOrderDescending按上映日期倒序最新入库的排在前面。响应长这样{ Items: [ { Id: b7e1f2a0-..., Name: 星际穿越, Type: Movie, PremiereDate: 2014-11-05T08:00:00Z } ], StartIndex: 0, Size: 20, TotalRecordCount: 42 }TotalRecordCount告诉你总数是 42 条Items里每一项的Id就是后续动数据要用的项目 ID。电影海报、简介这些元数据大多来自 OMDb 之类的元数据插件你在 App 里拿到的正是它们入库后的结果✍️ 第三关写入数据——按使用场景来写接口的返回大多是204 No Content没有响应体状态码本身就是你判断成功的依据。Jellyfin 播放进度上报示例你的播放器每 10 秒上报一次位置用POST /Sessions/Playing/Progresscurl -X POST http://127.0.0.1:8096/Sessions/Playing/Progress \ -H X-Emby-Token: a1b2c3d4e5f6g7h8i9j0 \ -H Content-Type: application/json \ -d { ItemId: b7e1f2a0-..., PositionTicks: 18000000000, IsPaused: false, PlayMethod: Transcode }注意PositionTicks的单位是 .NET 的 tick1 秒 10,000,000 ticks上例的 18000000000 就是播到了第 30 分钟。标记已看 / 取消已看比逐帧上报更简单的是直接改状态POST /UserPlayedItems/{itemId}标记已看DELETE /UserPlayedItems/{itemId}取消返回该项目的用户数据方便你校验curl -X POST http://127.0.0.1:8096/UserPlayedItems/b7e1f2a0-... \ -H X-Emby-Token: a1b2c3d4e5f6g7h8i9j0给家人开账号创建用户这是管理员专属接口对应源码里的RequiresElevation策略必须用管理员账户的令牌。POST /Users/Newcurl -X POST http://127.0.0.1:8096/Users/New \ -H X-Emby-Token: 管理员令牌 \ -H Content-Type: application/json \ -d {Name: xiaoming, Password: 初始密码}返回200和新用户的 DTO其中Id字段就是你后续给这个孩子账户发权限、查资料要用的用户 ID。新增媒体文件夹VirtualFolders新硬盘挂载好了想让 Jellyfin 收进去POST /Library/VirtualFolders新建一个虚拟文件夹curl -X POST http://127.0.0.1:8096/Library/VirtualFolders \ -H X-Emby-Token: 管理员令牌 \ -H Content-Type: application/json \ -d {CollectionType: movies, Name: 电影 2026, Locations: [/media/movies-2026]}CollectionType决定媒体库类型movies、tv、music、photos、books等。成功后可以再打GET /Library/VirtualFolders确认新文件夹已出现在列表里然后触发一次库扫描即可。 排错速查Jellyfin 接口 HTTP 状态码对照状态码常见含义先查什么400请求体或查询参数格式不对看返回的 errors 字段逐个修正401令牌缺失或无效X-Emby-Token是否拼错、令牌是否被吊销403权限不足该接口是否要求管理员令牌如创建用户404项目/用户不存在itemId、userId是否复制完整405HTTP 方法用错该接口是 GET 还是 POST500服务端异常翻服务器日志找对应时间点的堆栈参数类错误会返回标准的 JSON 问题详情例如登录时漏了Pw{ type: https://tools.ietf.org/html/rfc9110#section-15.5.1, title: One or more validation errors occurred., status: 400, errors: { Pw: [ The Pw field is required. ] } }而 5xx 在生产模式下只回一句Error processing request.具体原因要去服务器日志里看。排查思路记三句401 先怀疑令牌403 先怀疑账户角色500 直接看日志——认证逻辑在 Jellyfin.Api/Auth 和 Jellyfin.Server.Implementations/Security 里报错处理在 Jellyfin.Api/Middleware/ExceptionMiddleware.cs想深挖时可以对号入座。⚡ 提效小抄5 条实践清单分页用StartIndexLimit响应里的TotalRecordCount决定要不要翻下一页。列表查询加fields参数只取渲染界面真正需要的字段。令牌等同长期密码别硬编码在公开脚本里改动服务器密码后要重新登录换令牌。多设备共享令牌时给每个请求带上X-Emby-Client和X-Emby-Device-Id头当前会话页里才好区分是谁在播。懒得背接口就打开http://你的服务器:8096/docs那是随服务器附带的交互式完整 API 文档可以直接在线调试。写在最后到这里你手上已经有了一个能登录、能查库、能写数据的完整链路从 Jellyfin.Api/Controllers 里的几十个控制器挑出你要的接口用令牌换取信任剩下的就是循环和判断。把这套流程搬进你的遥控 App 或定时脚本再配合/docs页面查漏补缺绝大多数自动化需求都能自己解决遇到拿不准的行为去项目仓库的 issue 区或社区论坛看看大概率有人踩过同一个坑。【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Jellyfin API 实战教程：4 个关卡搞定认证、查询与数据写入
Jellyfin API 实战教程4 个关卡搞定认证、查询与数据写入【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin你想给家庭影院做个遥控 App或者写个脚本每天自动检查媒体库有没有新片入库只要 Jellyfin一个可自托管的开源媒体服务器跑在你的机器上这些事情都能通过它的 HTTP 接口——也就是Jellyfin API——完成。本文不讲抽象架构按动手闯关的顺序带你走完先拿到访问令牌再查一遍媒体库然后试着写入数据最后备一份排错速查。跟着做你就能把自己的 App 或脚本接进 Jellyfin。 第一关拿到 Jellyfin 认证令牌登录接口写法Jellyfin 的多数接口要求先登录换一张令牌。登录接口是POST /Users/AuthenticateByName把用户名和密码放在 JSON 请求体里curl -X POST http://127.0.0.1:8096/Users/AuthenticateByName \ -H Content-Type: application/json \ -d {Username: admin, Pw: 你的密码}响应里重点看两个字段{ AccessToken: a1b2c3d4e5f6g7h8i9j0, User: { Id: 3f2a8b9c-1d2e-4a3b-9c8d-0e1f2a3b4c5d, Name: admin }, SessionInfo: { Id: 6e5d4c3b-... } }AccessToken你的访问令牌后面每个请求都要带上User.Id用户 ID查询媒体库等接口要用到先存下来。拿到令牌后放进请求头的X-Emby-Token即可也可以写成Authorization: MediaBrowser Token...的形式二者等价curl http://127.0.0.1:8096/Users/Me \ -H X-Emby-Token: a1b2c3d4e5f6g7h8i9j0如果返回了你自己的用户信息说明令牌生效了第一关通过。想确认令牌是否还有效随时可以打这个GET /Users/Me。 第二关查询媒体库Jellyfin 接口调用示例现在用一次真实查询把类型过滤、分页、字段裁剪这些常用参数一次串起来。请求GET /Items带上上一关存下的用户 IDcurl http://127.0.0.1:8096/Items?userId3f2a8b9c-...includeItemTypesMovieRecursivetrueSortByPremiereDateSortOrderDescendingStartIndex0Limit20fieldsPrimaryImageAspectRatio \ -H X-Emby-Token: a1b2c3d4e5f6g7h8i9j0各参数在做什么includeItemTypesMovie只查电影换成Series、MusicAlbum或逗号分隔的多个类型也行Recursivetrue递归进入子文件夹StartIndex0Limit20分页第一页 20 条下一页把StartIndex改成 20fieldsPrimaryImageAspectRatio字段裁剪只额外返回你点名的字段省流量SortByPremiereDateSortOrderDescending按上映日期倒序最新入库的排在前面。响应长这样{ Items: [ { Id: b7e1f2a0-..., Name: 星际穿越, Type: Movie, PremiereDate: 2014-11-05T08:00:00Z } ], StartIndex: 0, Size: 20, TotalRecordCount: 42 }TotalRecordCount告诉你总数是 42 条Items里每一项的Id就是后续动数据要用的项目 ID。电影海报、简介这些元数据大多来自 OMDb 之类的元数据插件你在 App 里拿到的正是它们入库后的结果✍️ 第三关写入数据——按使用场景来写接口的返回大多是204 No Content没有响应体状态码本身就是你判断成功的依据。Jellyfin 播放进度上报示例你的播放器每 10 秒上报一次位置用POST /Sessions/Playing/Progresscurl -X POST http://127.0.0.1:8096/Sessions/Playing/Progress \ -H X-Emby-Token: a1b2c3d4e5f6g7h8i9j0 \ -H Content-Type: application/json \ -d { ItemId: b7e1f2a0-..., PositionTicks: 18000000000, IsPaused: false, PlayMethod: Transcode }注意PositionTicks的单位是 .NET 的 tick1 秒 10,000,000 ticks上例的 18000000000 就是播到了第 30 分钟。标记已看 / 取消已看比逐帧上报更简单的是直接改状态POST /UserPlayedItems/{itemId}标记已看DELETE /UserPlayedItems/{itemId}取消返回该项目的用户数据方便你校验curl -X POST http://127.0.0.1:8096/UserPlayedItems/b7e1f2a0-... \ -H X-Emby-Token: a1b2c3d4e5f6g7h8i9j0给家人开账号创建用户这是管理员专属接口对应源码里的RequiresElevation策略必须用管理员账户的令牌。POST /Users/Newcurl -X POST http://127.0.0.1:8096/Users/New \ -H X-Emby-Token: 管理员令牌 \ -H Content-Type: application/json \ -d {Name: xiaoming, Password: 初始密码}返回200和新用户的 DTO其中Id字段就是你后续给这个孩子账户发权限、查资料要用的用户 ID。新增媒体文件夹VirtualFolders新硬盘挂载好了想让 Jellyfin 收进去POST /Library/VirtualFolders新建一个虚拟文件夹curl -X POST http://127.0.0.1:8096/Library/VirtualFolders \ -H X-Emby-Token: 管理员令牌 \ -H Content-Type: application/json \ -d {CollectionType: movies, Name: 电影 2026, Locations: [/media/movies-2026]}CollectionType决定媒体库类型movies、tv、music、photos、books等。成功后可以再打GET /Library/VirtualFolders确认新文件夹已出现在列表里然后触发一次库扫描即可。 排错速查Jellyfin 接口 HTTP 状态码对照状态码常见含义先查什么400请求体或查询参数格式不对看返回的 errors 字段逐个修正401令牌缺失或无效X-Emby-Token是否拼错、令牌是否被吊销403权限不足该接口是否要求管理员令牌如创建用户404项目/用户不存在itemId、userId是否复制完整405HTTP 方法用错该接口是 GET 还是 POST500服务端异常翻服务器日志找对应时间点的堆栈参数类错误会返回标准的 JSON 问题详情例如登录时漏了Pw{ type: https://tools.ietf.org/html/rfc9110#section-15.5.1, title: One or more validation errors occurred., status: 400, errors: { Pw: [ The Pw field is required. ] } }而 5xx 在生产模式下只回一句Error processing request.具体原因要去服务器日志里看。排查思路记三句401 先怀疑令牌403 先怀疑账户角色500 直接看日志——认证逻辑在 Jellyfin.Api/Auth 和 Jellyfin.Server.Implementations/Security 里报错处理在 Jellyfin.Api/Middleware/ExceptionMiddleware.cs想深挖时可以对号入座。⚡ 提效小抄5 条实践清单分页用StartIndexLimit响应里的TotalRecordCount决定要不要翻下一页。列表查询加fields参数只取渲染界面真正需要的字段。令牌等同长期密码别硬编码在公开脚本里改动服务器密码后要重新登录换令牌。多设备共享令牌时给每个请求带上X-Emby-Client和X-Emby-Device-Id头当前会话页里才好区分是谁在播。懒得背接口就打开http://你的服务器:8096/docs那是随服务器附带的交互式完整 API 文档可以直接在线调试。写在最后到这里你手上已经有了一个能登录、能查库、能写数据的完整链路从 Jellyfin.Api/Controllers 里的几十个控制器挑出你要的接口用令牌换取信任剩下的就是循环和判断。把这套流程搬进你的遥控 App 或定时脚本再配合/docs页面查漏补缺绝大多数自动化需求都能自己解决遇到拿不准的行为去项目仓库的 issue 区或社区论坛看看大概率有人踩过同一个坑。【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考