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），僅供參考