Jellyfin API 使用完整指南从认证到常用接口【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfinJellyfin 是一套自托管媒体系统的后端与 API它把你的电影、剧集、音乐文件组织成带元数据的媒体库并对外开放一套 REST 接口。本文基于仓库源码整理跟着做你可以拿到认证令牌、查询媒体库、并把内容标记为已观看。三分钟跑通 最短路径就三步换令牌、发请求、读响应。假设服务器跑在http://localhost:8096。第一步用账号密码换取访问令牌。接口是POST /Users/AuthenticateByName请求体字段来自 AuthenticateUserByName.cs注意密码字段叫Pw而不是Passwordcurl -X POST http://localhost:8096/Users/AuthenticateByName \ -H Content-Type: application/json \ -d {Username: alice, Pw: demo-pass-2026}第二步带着令牌查媒体库。认证头的前缀必须是MediaBrowser这一点在 AuthorizationContext.cs 中校验curl http://localhost:8096/Items?includeItemTypesMovielimit5 \ -H Authorization: MediaBrowser Token0c8f2a7e4d1b4f6a9e3c5b8d1a2f7e4c第三步看响应。返回结构是QueryResult关键字段如下其余字段省略{ Items: [ { Id: 7c9d3e21-5b48-4f16-9a02-3d8e6c5b1f09, Name: 示例影片, Type: Movie, PremiereDate: 2023-05-01T00:00:00Z, RunTimeTicks: 72000000000 } ], TotalRecordCount: 38, StartIndex: 0 }能拿到Items数组就说明链路通了。接口在哪找Jellyfin 用 ASP.NET Core 控制器生成 OpenAPI 文档服务器内置了两个在线入口见 ApiApplicationBuilderExtensions.cshttp://localhost:8096/api-docs/swagger/— Swagger UI可按 Tag 浏览、在线试用http://localhost:8096/api-docs/openapi.json— 完整的 OpenAPI 规范适合丢给工具或 IDE 插件。 不想翻在线文档时直接看源码目录 Jellyfin.Api/Controllers/每个*Controller.cs文件对应一组接口类上的[Route]特性给出基础路径方法上的[HttpGet]、[HttpPost]特性给出具体路由。例如 ItemsController.cs 标注了[HttpGet(Items)]对应GET /Items。参数名和类型就写在方法签名里比文档更新更及时。高频接口走查如何获取 Jellyfin 认证令牌POST /Users/AuthenticateByNameUserController.cs是普通客户端的登录入口。关键参数Username、Pw都是 PascalCase响应关键字段AccessToken令牌、User.Id后续userId参数的来源令牌如何生效AuthorizationContext.cs 拿到令牌后先查设备表再查 API Key 表把令牌映射到用户和角色。令牌本身没有过期时间删除对应会话或 Key 即失效。Jellyfin 媒体列表查询接口参数说明GET /ItemsItemsController.cs是查询的主力接口参数很多日常最常用的是这几个includeItemTypes按类型过滤多个用逗号分隔如Movie,Serieslimit/startIndex分页用startIndex缺省为 0fields追加返回字段如Overview,MediaStreams能显著减小响应体积。 响应里每个项目默认就带Id、Name、Type和海报信息海报与简介由元数据插件填充如何把内容标记为已观看POST /UserPlayedItems/{itemId}?userId...PlaystateController.cs更新某个用户对某条内容的播放记录curl -X POST http://localhost:8096/UserPlayedItems/7c9d3e21-5b48-4f16-9a02-3d8e6c5b1f09?userId3f2a9c81-bb45-4e0d-8a17-6c5d2e9f0b34 \ -H Authorization: MediaBrowser Token0c8f2a7e4d1b4f6a9e3c5b8d1a2f7e4citemId路径参数从/Items结果里取IduserId查询参数缺省则用令牌对应用户响应是UserItemDataDto其中PlayCount、Played直接反映更新结果取消观看用DELETE同一路径。踩坑排查状态码常见原因解决办法401令牌缺失、写错或会话已被服务端清除重新调AuthenticateByName换令牌检查认证头前缀是否为MediaBrowser不是Bearer403权限不足管理接口标了[Authorize(Policy Policies.RequiresElevation)]需用管理员账号或 API Key404路径打错或该用户无权访问此条目先用 Swagger 核对路由确认itemId属于当前用户可见的库几条有具体原因的调试经验参数大小写不一致。URL 查询参数是 camelCasestartIndex、limitJSON 请求体是 PascalCaseUsername、Pw。混用时参数会被静默忽略表现为条件没生效而不是报错。认证头前缀写错。源码只认MediaBrowserX-Emby-Token、X-Emby-Authorization等旧式头只在服务端开启EnableLegacyAuthorization时可用新部署默认关闭。别用普通令牌干管理员的事。给脚本发一个长期 API KeyPOST /ApiKeys它在鉴权时直接映射为管理员角色且不与某个会话绑定比反复登录稳。进阶技巧分页大查询务必带startIndexlimit循环拉取响应里的TotalRecordCount告诉你何时该停。字段过滤只取需要的数据时给fields传白名单如Overview,ProviderIds网络体积可降一大截。令牌管理用户令牌绑定设备与会话被清理就失效自动化任务优先用 API Key通过?ApiKey...查询参数传递同样有效见 AuthorizationContext.cs。兼容旧客户端Users/{userId}/Items这类Users前缀路由是遗留兼容路径源码中标注了 Obsolete新代码应使用UserItems、/Items等现行路径。升级前比对规范把openapi.json纳入版本对比接口删改会在升级时一目了然具体行为以源码为准。写在最后Jellyfin API 的价值在于令牌一次换取之后查询、元数据、播放状态全部走同一套 REST 约定。想深入就从 Jellyfin.Api/Controllers/ 的控制器源码和/api-docs/swagger/页面入手遇到拿不准的参数直接搜方法签名即可。【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考