Jellyfin API 实战指南：十分钟打通第一个请求，外加四个必踩的坑

Jellyfin API 实战指南十分钟打通第一个请求外加四个必踩的坑【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfinJellyfin 服务端的 API 以 RESTful 风格资源映射到 URL、用 GET/POST 等方法操作暴露任何业务请求都要先过一道认证关。这篇不铺概念直接走通闭环拿令牌、查片库、报播放、兜错误每一步标出最容易卡住的地方。1️⃣ 坑一认证头少了前缀请求永远是 401第一步永远是拿用户名密码换 AccessToken一串凭证字符串证明已登录之后每次请求都要带上它。POST /Users/AuthenticateByName Content-Type: application/json { Username: YOUR_USERNAME, Pw: YOUR_PASSWORD }成功后返回令牌和用户信息{ AccessToken: YOUR_TOKEN_HERE, User: { Id: user-id, Name: YOUR_USERNAME } // …省略 }第二步才是多数人翻车的点带令牌不能写裸的Authorization: Bearer ...。Jellyfin 沿用的是 MediaBrowser Token 前缀一套自定义认证方案的写法令牌值外面的引号也不能省Authorization: MediaBrowser TokenYOUR_TOKEN_HERE这个头部由专门的认证处理器解析见 CustomAuthenticationHandler 源码。前缀拼错、引号漏掉令牌都等于没带直接 401。另外注意登录参数是Pw不是Password端点定义在 UserController。2️⃣ 坑二查 /Items 忘带 userId或 limit 拍脑袋拿到令牌后先取媒体列表。userId是查询的必备参数不用 API key 时服务端得知道替谁查GET /Items?userIduser-idincludeItemTypesMoviesortBySortNamestartIndex0limit25 Authorization: MediaBrowser TokenYOUR_TOKEN_HEREincludeItemTypes类型过滤多值用逗号分隔如Movie,SeriesstartIndex/limit分页从下标 0 开始limit建议控制在 25~100fields只取你要的字段压小响应体积持有 API key 的场景下userId可以不传令牌本身就代表身份。响应是带分页外壳的结构{ Items: [ { Id: item-id, Name: Sample Movie, Type: Movie, RunTimeTicks: 72000000000 // …省略 } ], TotalRecordCount: 42, StartIndex: 0, Limit: 25 }limit别贪大一次性拉几万部片是超时的高发场景遍历全库就用startIndex翻页。filters、mediaTypes等完整参数在 ItemsController 里都有注释不确定就先少传。3️⃣ 坑三把报进度和标看过当成同一个接口播放状态Playstate泛指正在播什么、播到哪的接口族其实分两路回写播放会话状态开始、进度、停止三件事现行入口是POST /Sessions/Playing/Progress观看状态POST /UserPlayedItems/{itemId}标记已看完对同一路径DELETE再标记回未看。POST /Sessions/Playing/Progress Authorization: MediaBrowser TokenYOUR_TOKEN_HERE Content-Type: application/json { ItemId: item-id, PlaySessionId: play-session-id, PlayMethod: Transcode, PositionTicks: 36000000000, IsPaused: false // …省略 }成功返回 204 No Content没有响应体。两个易错点PositionTicks用的是 .NET 时间单位1 秒 10,000,000 ticks上面的值表示播到 1 小时PlaySessionId要在播放开始时生成先报POST /Sessions/Playing。服务端找不到对应的转码任务时你报的Transcode会被自动纠正成DirectPlay。相关端点集中在 PlaystateController。旧路由POST /PlayingItems/{itemId}/Progress已标注 Obsolete新代码别用它。4️⃣ 坑四状态码只会看 401漏掉两个细节状态码典型成因401令牌没带、或头部格式写错403资源没权限如非管理员调管理端点404item id 不存在或该用户看不到这件204报进度这类写操作成功无响应体两个隐藏细节404 不一定是 id 敲错。同一件媒体对部分用户可能不可见媒体库按用户隔离可见性先换该用户视角确认再怀疑 id用户修改密码后服务端会吊销其名下全部旧令牌仅保留改密时正在使用的那个。长驻任务若拿着旧令牌会突然从 200 变 401登录失败后要有重取令牌的兜底逻辑。一次请求的完整走位把四步串起来就是接入的最小闭环卡住时按顺序排查头部前缀和引号 → 请求里的userId→ 令牌是否因改密被吊销。走完这条链路Jellyfin 的服务端接入就算打通了。【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考