Jellyfin API 使用完整指南從認證到常用接口【免費下載鏈接】jellyfinThe Free Software Media System - Server Backend API項目地址: https://gitcode.com/GitHub_Trending/je/jellyfinJellyfin 是一套自托管媒體系統(tǒng)的后端與 API它把你的電影、劇集、音樂文件組織成帶元數(shù)據(jù)的媒體庫并對外開放一套 REST 接口。本文基于倉庫源碼整理跟著做你可以拿到認證令牌、查詢媒體庫、并把內(nèi)容標記為已觀看。三分鐘跑通 最短路徑就三步換令牌、發(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第三步看響應。返回結(jié)構(gòu)是QueryResult關(guān)鍵字段如下其余字段省略{ 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 文檔服務器內(nèi)置了兩個在線入口見 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是普通客戶端的登錄入口。關(guān)鍵參數(shù)Username、Pw都是 PascalCase響應關(guān)鍵字段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ù)據(jù)插件填充如何把內(nèi)容標記為已觀看POST /UserPlayedItems/{itemId}?userId...PlaystateController.cs更新某個用戶對某條內(nèi)容的播放記錄curl -X POST http://localhost:8096/UserPlayedItems/7c9d3e21-5b48-4f16-9a02-3d8e6c5b1f09?userId3f2a9c81-bb45-4e0d-8a17-6c5d2e9f0b34 \ -H Authorization: MediaBrowser Token0c8f2a7e4d1b4f6a9e3c5b8d1a2f7e4citemId路徑參數(shù)從/Items結(jié)果里取IduserId查詢參數(shù)缺省則用令牌對應用戶響應是UserItemDataDto其中PlayCount、Played直接反映更新結(jié)果取消觀看用DELETE同一路徑。踩坑排查狀態(tài)碼常見原因解決辦法401令牌缺失、寫錯或會話已被服務端清除重新調(diào)AuthenticateByName換令牌檢查認證頭前綴是否為MediaBrowser不是Bearer403權(quán)限不足管理接口標了[Authorize(Policy Policies.RequiresElevation)]需用管理員賬號或 API Key404路徑打錯或該用戶無權(quán)訪問此條目先用 Swagger 核對路由確認itemId屬于當前用戶可見的庫幾條有具體原因的調(diào)試經(jīng)驗參數(shù)大小寫不一致。URL 查詢參數(shù)是 camelCasestartIndex、limitJSON 請求體是 PascalCaseUsername、Pw?；煊脮r參數(shù)會被靜默忽略表現(xiàn)為條件沒生效而不是報錯。認證頭前綴寫錯。源碼只認MediaBrowserX-Emby-Token、X-Emby-Authorization等舊式頭只在服務端開啟EnableLegacyAuthorization時可用新部署默認關(guān)閉。別用普通令牌干管理員的事。給腳本發(fā)一個長期 API KeyPOST /ApiKeys它在鑒權(quán)時直接映射為管理員角色且不與某個會話綁定比反復登錄穩(wěn)。進階技巧分頁大查詢務必帶startIndexlimit循環(huán)拉取響應里的TotalRecordCount告訴你何時該停。字段過濾只取需要的數(shù)據(jù)時給fields傳白名單如Overview,ProviderIds網(wǎng)絡體積可降一大截。令牌管理用戶令牌綁定設備與會話被清理就失效自動化任務優(yōu)先用 API Key通過?ApiKey...查詢參數(shù)傳遞同樣有效見 AuthorizationContext.cs。兼容舊客戶端Users/{userId}/Items這類Users前綴路由是遺留兼容路徑源碼中標注了 Obsolete新代碼應使用UserItems、/Items等現(xiàn)行路徑。升級前比對規(guī)范把openapi.json納入版本對比接口刪改會在升級時一目了然具體行為以源碼為準。寫在最后Jellyfin API 的價值在于令牌一次換取之后查詢、元數(shù)據(jù)、播放狀態(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)作聲明：本文部分內(nèi)容由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ù)據(jù)的媒體庫并對外開放一套 REST 接口。本文基于倉庫源碼整理跟著做你可以拿到認證令牌、查詢媒體庫、并把內(nèi)容標記為已觀看。三分鐘跑通 最短路徑就三步換令牌、發(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第三步看響應。返回結(jié)構(gòu)是QueryResult關(guān)鍵字段如下其余字段省略{ 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 文檔服務器內(nèi)置了兩個在線入口見 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是普通客戶端的登錄入口。關(guān)鍵參數(shù)Username、Pw都是 PascalCase響應關(guān)鍵字段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ù)據(jù)插件填充如何把內(nèi)容標記為已觀看POST /UserPlayedItems/{itemId}?userId...PlaystateController.cs更新某個用戶對某條內(nèi)容的播放記錄curl -X POST http://localhost:8096/UserPlayedItems/7c9d3e21-5b48-4f16-9a02-3d8e6c5b1f09?userId3f2a9c81-bb45-4e0d-8a17-6c5d2e9f0b34 \ -H Authorization: MediaBrowser Token0c8f2a7e4d1b4f6a9e3c5b8d1a2f7e4citemId路徑參數(shù)從/Items結(jié)果里取IduserId查詢參數(shù)缺省則用令牌對應用戶響應是UserItemDataDto其中PlayCount、Played直接反映更新結(jié)果取消觀看用DELETE同一路徑。踩坑排查狀態(tài)碼常見原因解決辦法401令牌缺失、寫錯或會話已被服務端清除重新調(diào)AuthenticateByName換令牌檢查認證頭前綴是否為MediaBrowser不是Bearer403權(quán)限不足管理接口標了[Authorize(Policy Policies.RequiresElevation)]需用管理員賬號或 API Key404路徑打錯或該用戶無權(quán)訪問此條目先用 Swagger 核對路由確認itemId屬于當前用戶可見的庫幾條有具體原因的調(diào)試經(jīng)驗參數(shù)大小寫不一致。URL 查詢參數(shù)是 camelCasestartIndex、limitJSON 請求體是 PascalCaseUsername、Pw?；煊脮r參數(shù)會被靜默忽略表現(xiàn)為條件沒生效而不是報錯。認證頭前綴寫錯。源碼只認MediaBrowserX-Emby-Token、X-Emby-Authorization等舊式頭只在服務端開啟EnableLegacyAuthorization時可用新部署默認關(guān)閉。別用普通令牌干管理員的事。給腳本發(fā)一個長期 API KeyPOST /ApiKeys它在鑒權(quán)時直接映射為管理員角色且不與某個會話綁定比反復登錄穩(wěn)。進階技巧分頁大查詢務必帶startIndexlimit循環(huán)拉取響應里的TotalRecordCount告訴你何時該停。字段過濾只取需要的數(shù)據(jù)時給fields傳白名單如Overview,ProviderIds網(wǎng)絡體積可降一大截。令牌管理用戶令牌綁定設備與會話被清理就失效自動化任務優(yōu)先用 API Key通過?ApiKey...查詢參數(shù)傳遞同樣有效見 AuthorizationContext.cs。兼容舊客戶端Users/{userId}/Items這類Users前綴路由是遺留兼容路徑源碼中標注了 Obsolete新代碼應使用UserItems、/Items等現(xiàn)行路徑。升級前比對規(guī)范把openapi.json納入版本對比接口刪改會在升級時一目了然具體行為以源碼為準。寫在最后Jellyfin API 的價值在于令牌一次換取之后查詢、元數(shù)據(jù)、播放狀態(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)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考