Jellyfin API 实战指南从获取令牌到媒体管理4 个场景跑通核心接口【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin场景引入Jellyfin API 是 Jellyfin 服务器对外暴露的一组 RESTful 接口任何能发出 HTTP 请求的程序都可以用它读写媒体库。假设你正在开发一个家庭影院助手应用媒体数据存放在家里的 Jellyfin 服务器上这类应用不需要了解服务器内部如何扫描文件、如何抓取元数据只需要一套稳定的接口来读库、建号、同步播放进度。接口按功能拆分在多个 Controller 中源码集中在Jellyfin.Api/Controllers目录。本文按上手的自然顺序推进先完成认证拿到访问令牌再用四个场景把常用接口逐一跑通最后附上控制器速查表与错误码对照方便日后查阅。第一步拿到访问令牌需要身份的请求都从同一个入口开始先向POST /Users/AuthenticateByName提交用户名与密码。POST /Users/AuthenticateByName Content-Type: application/json { Username: admin, Pw: password }服务器校验通过后返回体里带出一个AccessToken和用户基本信息{ AccessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..., User: { Id: a1b2c3d4-e5f6-4a5b-9c8d-7e6f5a4b3c2d, Name: admin } }AccessToken就是后续所有请求要用的令牌User.Id则要在多数查询接口里作为参数继续带上。身份声明通过Authorization头按 MediaBrowser 方案写入GET /Items Authorization: MediaBrowser TokeneyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...整个认证与后续调用的交互过程如下第二步四个场景实操场景 1获取媒体列表要实现什么从媒体库中按类型取出一批条目。GET /Items?userIda1b2c3d4-e5f6-4a5b-9c8d-7e6f5a4b3c2dincludeItemTypesMovielimit10userId发起查询的用户 Id必填includeItemTypes按类型过滤Movie、Series、Music 等多类型用逗号分隔limit本次返回的条目上限响应是标准分页结构Items为条目数组条目内含Id、Name、Type、PremiereDate、RunTimeTicks等字段TotalRecordCount是库中符合条件的总条数配合startIndex即可翻页。{ Items: [ { Id: b2c3d4e5-f6a7-5b6c-0d1e-8f9a0b1c2d3e, Name: Sample Movie, Type: Movie, PremiereDate: 2023-01-01T00:00:00Z, RunTimeTicks: 72000000000 } ], TotalRecordCount: 42 }场景 2创建与查看用户要实现什么为家庭成员开一个独立账号并确认账号已写入。先调用POST /Users/New这一步交给 UserController 处理令牌必须来自管理员账号POST /Users/New Authorization: MediaBrowser TokeneyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Content-Type: application/json { Name: new_user, Password: secure_password }Name新账号名Password初始密码权限不足时接口会直接拒绝403令牌权限不够是这类操作最常见的失败原因创建完成后用列表接口核对结果GET /Users Authorization: MediaBrowser TokeneyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...两个接口的返回都是 JSON创建接口回传新账号的完整信息含 Id列表接口回传全部账号数组比对Name字段即可确认写入成功。场景 3上报播放进度要实现什么客户端播放到某个时间点时把进度同步回服务器让继续播放功能可用。POST /Items/{itemId}/Playback/Progress Authorization: MediaBrowser TokeneyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Content-Type: application/json { PositionTicks: 36000000000, PlaybackStartTime: 2023-10-01T12:00:00Z, IsPaused: false }itemId路径参数取条目在库中的 IdPositionTicks当前播放位置单位是 tick每秒 10,000,000 tickPlaybackStartTime本次播放的起始时间IsPausedtrue 表示暂停false 表示正常播放上报成功后服务器更新该用户的播放状态itemId不存在或无访问权限时按相应状态码返回错误。场景 4新建媒体库要实现什么把新增的一批文件夹挂到服务器上形成一个可浏览的虚拟媒体库。POST /Library/VirtualFolders Authorization: MediaBrowser TokeneyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Content-Type: application/json { Name: Family Photos, CollectionType: photos, Locations: [/media/photos/family], RefreshLibrary: true }Name库名即客户端界面上显示的名称CollectionType库类型决定扫描与展示方式movies、tvshows、photos 等Locations服务器本地路径数组支持多个目录RefreshLibrary置为 true 时创建后立即触发一次扫描该操作在后台异步执行接口先行返回扫描进度可通过服务器状态接口另行观察。速查表核心控制器一览控制器功能描述典型用途ItemsController媒体项目管理电影、音乐、剧集等查询条目、按类型过滤、分页列表UserController用户账户管理与认证登录换取令牌、创建与修改账号LibraryController媒体库管理增删虚拟媒体库、读取库配置PlaylistsController播放列表操作新建、编辑播放列表VideosController视频资源专用接口视频流传输与转码控制AudioController音频资源专用接口音频流传输、附件与字幕处理排错速查常见错误码 状态码含义200 OK请求成功400 Bad Request请求参数错误401 Unauthorized认证失败403 Forbidden权限不足404 Not Found资源不存在500 Internal Server Error服务器内部错误错误响应的一般形态{ error: { code: Unauthorized, message: Invalid authentication token } }进阶建议 令牌管理AccessToken存入服务端安全位置环境变量或密钥文件失效后重新走AuthenticateByName获取避免硬编码进代码。分页与字段裁剪大数据集用startIndex加limit翻页用fields参数只取需要的字段压缩响应体积。批量与缓存相似的多个查询尽量合并参数一次发出重复的元数据在本地做缓存减少请求次数。版本兼容升级服务器前对照接口变更记录核对依赖的路径与参数旧版接口可能仅作为兼容层保留。更多字段语义与接口细节请以 Jellyfin 官方 API 文档为准具体问题可到社区讨论区交流。【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考