Jellyfin API 使用完整指南從認證到常用接口【免費下載鏈接】jellyfinThe Free Software Media System - Server Backend API項目地址: https://gitcode.com/GitHub_Trending/je/jellyfinJellyfin 是一套自托管媒體系統(tǒng)的后端與 API它把你的電影、劇集、音樂文件組織成帶元數(shù)據的媒體庫并對外開放一套 REST 接口。本文基于倉庫源碼整理跟著做你可以拿到認證令牌、查詢媒體庫、并把內容標記為已觀看。三分鐘跑通 最短路徑就三步換令牌、發(fā)請求、讀響應。假設服務器跑在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數(shù)組就說明鏈路通了。接口在哪找Jellyfin 用 ASP.NET Core 控制器生成 OpenAPI 文檔服務器內置了兩個在線入口見 ApiApplicationBuilderExtensions.cshttp://localhost:8096/api-docs/swagger/— Swagger UI可按 Tag 瀏覽、在線試用http://localhost:8096/api-docs/openapi.json— 完整的 OpenAPI 規(guī)范適合丟給工具或 IDE 插件。 不想翻在線文檔時直接看源碼目錄 Jellyfin.Api/Controllers/每個*Controller.cs文件對應一組接口類上的[Route]特性給出基礎路徑方法上的[HttpGet]、[HttpPost]特性給出具體路由。例如 ItemsController.cs 標注了[HttpGet(Items)]對應GET /Items。參數(shù)名和類型就寫在方法簽名里比文檔更新更及時。高頻接口走查如何獲取 Jellyfin 認證令牌POST /Users/AuthenticateByNameUserController.cs是普通客戶端的登錄入口。關鍵參數(shù)Username、Pw都是 PascalCase響應關鍵字段AccessToken令牌、User.Id后續(xù)userId參數(shù)的來源令牌如何生效AuthorizationContext.cs 拿到令牌后先查設備表再查 API Key 表把令牌映射到用戶和角色。令牌本身沒有過期時間刪除對應會話或 Key 即失效。Jellyfin 媒體列表查詢接口參數(shù)說明GET /ItemsItemsController.cs是查詢的主力接口參數(shù)很多日常最常用的是這幾個includeItemTypes按類型過濾多個用逗號分隔如Movie,Serieslimit/startIndex分頁用startIndex缺省為 0fields追加返回字段如Overview,MediaStreams能顯著減小響應體積。 響應里每個項目默認就帶Id、Name、Type和海報信息海報與簡介由元數(shù)據插件填充如何把內容標記為已觀看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路徑參數(shù)從/Items結果里取IduserId查詢參數(shù)缺省則用令牌對應用戶響應是UserItemDataDto其中PlayCount、Played直接反映更新結果取消觀看用DELETE同一路徑。踩坑排查狀態(tài)碼常見原因解決辦法401令牌缺失、寫錯或會話已被服務端清除重新調AuthenticateByName換令牌檢查認證頭前綴是否為MediaBrowser不是Bearer403權限不足管理接口標了[Authorize(Policy Policies.RequiresElevation)]需用管理員賬號或 API Key404路徑打錯或該用戶無權訪問此條目先用 Swagger 核對路由確認itemId屬于當前用戶可見的庫幾條有具體原因的調試經驗參數(shù)大小寫不一致。URL 查詢參數(shù)是 camelCasestartIndex、limitJSON 請求體是 PascalCaseUsername、Pw?；煊脮r參數(shù)會被靜默忽略表現(xiàn)為條件沒生效而不是報錯。認證頭前綴寫錯。源碼只認MediaBrowserX-Emby-Token、X-Emby-Authorization等舊式頭只在服務端開啟EnableLegacyAuthorization時可用新部署默認關閉。別用普通令牌干管理員的事。給腳本發(fā)一個長期 API KeyPOST /ApiKeys它在鑒權時直接映射為管理員角色且不與某個會話綁定比反復登錄穩(wěn)。進階技巧分頁大查詢務必帶startIndexlimit循環(huán)拉取響應里的TotalRecordCount告訴你何時該停。字段過濾只取需要的數(shù)據時給fields傳白名單如Overview,ProviderIds網絡體積可降一大截。令牌管理用戶令牌綁定設備與會話被清理就失效自動化任務優(yōu)先用 API Key通過?ApiKey...查詢參數(shù)傳遞同樣有效見 AuthorizationContext.cs。兼容舊客戶端Users/{userId}/Items這類Users前綴路由是遺留兼容路徑源碼中標注了 Obsolete新代碼應使用UserItems、/Items等現(xiàn)行路徑。升級前比對規(guī)范把openapi.json納入版本對比接口刪改會在升級時一目了然具體行為以源碼為準。寫在最后Jellyfin API 的價值在于令牌一次換取之后查詢、元數(shù)據、播放狀態(tài)全部走同一套 REST 約定。想深入就從 Jellyfin.Api/Controllers/ 的控制器源碼和/api-docs/swagger/頁面入手遇到拿不準的參數(shù)直接搜方法簽名即可?！久赓M下載鏈接】jellyfinThe Free Software Media System - Server Backend API項目地址: https://gitcode.com/GitHub_Trending/je/jellyfin創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 Jellyfin API 使用完整指南：從認證到常用接口
Jellyfin API 使用完整指南從認證到常用接口【免費下載鏈接】jellyfinThe Free Software Media System - Server Backend API項目地址: https://gitcode.com/GitHub_Trending/je/jellyfinJellyfin 是一套自托管媒體系統(tǒng)的后端與 API它把你的電影、劇集、音樂文件組織成帶元數(shù)據的媒體庫并對外開放一套 REST 接口。本文基于倉庫源碼整理跟著做你可以拿到認證令牌、查詢媒體庫、并把內容標記為已觀看。三分鐘跑通 最短路徑就三步換令牌、發(fā)請求、讀響應。假設服務器跑在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數(shù)組就說明鏈路通了。接口在哪找Jellyfin 用 ASP.NET Core 控制器生成 OpenAPI 文檔服務器內置了兩個在線入口見 ApiApplicationBuilderExtensions.cshttp://localhost:8096/api-docs/swagger/— Swagger UI可按 Tag 瀏覽、在線試用http://localhost:8096/api-docs/openapi.json— 完整的 OpenAPI 規(guī)范適合丟給工具或 IDE 插件。 不想翻在線文檔時直接看源碼目錄 Jellyfin.Api/Controllers/每個*Controller.cs文件對應一組接口類上的[Route]特性給出基礎路徑方法上的[HttpGet]、[HttpPost]特性給出具體路由。例如 ItemsController.cs 標注了[HttpGet(Items)]對應GET /Items。參數(shù)名和類型就寫在方法簽名里比文檔更新更及時。高頻接口走查如何獲取 Jellyfin 認證令牌POST /Users/AuthenticateByNameUserController.cs是普通客戶端的登錄入口。關鍵參數(shù)Username、Pw都是 PascalCase響應關鍵字段AccessToken令牌、User.Id后續(xù)userId參數(shù)的來源令牌如何生效AuthorizationContext.cs 拿到令牌后先查設備表再查 API Key 表把令牌映射到用戶和角色。令牌本身沒有過期時間刪除對應會話或 Key 即失效。Jellyfin 媒體列表查詢接口參數(shù)說明GET /ItemsItemsController.cs是查詢的主力接口參數(shù)很多日常最常用的是這幾個includeItemTypes按類型過濾多個用逗號分隔如Movie,Serieslimit/startIndex分頁用startIndex缺省為 0fields追加返回字段如Overview,MediaStreams能顯著減小響應體積。 響應里每個項目默認就帶Id、Name、Type和海報信息海報與簡介由元數(shù)據插件填充如何把內容標記為已觀看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路徑參數(shù)從/Items結果里取IduserId查詢參數(shù)缺省則用令牌對應用戶響應是UserItemDataDto其中PlayCount、Played直接反映更新結果取消觀看用DELETE同一路徑。踩坑排查狀態(tài)碼常見原因解決辦法401令牌缺失、寫錯或會話已被服務端清除重新調AuthenticateByName換令牌檢查認證頭前綴是否為MediaBrowser不是Bearer403權限不足管理接口標了[Authorize(Policy Policies.RequiresElevation)]需用管理員賬號或 API Key404路徑打錯或該用戶無權訪問此條目先用 Swagger 核對路由確認itemId屬于當前用戶可見的庫幾條有具體原因的調試經驗參數(shù)大小寫不一致。URL 查詢參數(shù)是 camelCasestartIndex、limitJSON 請求體是 PascalCaseUsername、Pw?；煊脮r參數(shù)會被靜默忽略表現(xiàn)為條件沒生效而不是報錯。認證頭前綴寫錯。源碼只認MediaBrowserX-Emby-Token、X-Emby-Authorization等舊式頭只在服務端開啟EnableLegacyAuthorization時可用新部署默認關閉。別用普通令牌干管理員的事。給腳本發(fā)一個長期 API KeyPOST /ApiKeys它在鑒權時直接映射為管理員角色且不與某個會話綁定比反復登錄穩(wěn)。進階技巧分頁大查詢務必帶startIndexlimit循環(huán)拉取響應里的TotalRecordCount告訴你何時該停。字段過濾只取需要的數(shù)據時給fields傳白名單如Overview,ProviderIds網絡體積可降一大截。令牌管理用戶令牌綁定設備與會話被清理就失效自動化任務優(yōu)先用 API Key通過?ApiKey...查詢參數(shù)傳遞同樣有效見 AuthorizationContext.cs。兼容舊客戶端Users/{userId}/Items這類Users前綴路由是遺留兼容路徑源碼中標注了 Obsolete新代碼應使用UserItems、/Items等現(xiàn)行路徑。升級前比對規(guī)范把openapi.json納入版本對比接口刪改會在升級時一目了然具體行為以源碼為準。寫在最后Jellyfin API 的價值在于令牌一次換取之后查詢、元數(shù)據、播放狀態(tài)全部走同一套 REST 約定。想深入就從 Jellyfin.Api/Controllers/ 的控制器源碼和/api-docs/swagger/頁面入手遇到拿不準的參數(shù)直接搜方法簽名即可?！久赓M下載鏈接】jellyfinThe Free Software Media System - Server Backend API項目地址: https://gitcode.com/GitHub_Trending/je/jellyfin創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考