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