在 Ubuntu 上使用 Jellyfin API 的实用指南
一 环境准备与获取访问凭证
- 安装并启动 Jellyfin（Ubuntu 20.04/22.04/24.04 可用 APT 源一键安装）：
- 添加源与密钥：
- sudo apt update && sudo apt install -y apt-transport-https ca-certificates gnupg curl
- sudo mkdir -p /etc/apt/keyrings
- curl -fsSL https://repo.jellyfin.org/jellyfin_team.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/jellyfin.gpg
- echo “deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/jellyfin.gpg] https://repo.jellyfin.org/$(awk -F= ‘/^ID=/{print $NF}’ /etc/os-release) $(awk -F= ‘/^VERSION_CODENAME=/{print $NF}’ /etc/os-release) main” | sudo tee /etc/apt/sources.list.d/jellyfin.sources
- 安装与启动：
- sudo apt update && sudo apt install -y jellyfin
- sudo systemctl enable --now jellyfin
- 获取 API 访问凭证（两种方式，任选其一）：
- 管理员 Token：在 Web 管理后台进入「控制台 → API Keys」，新建一个 Key（名称自定义，如 ubuntu-script）。
- 用户级 Token：登录 Web 后访问「http://服务器IP:8096/swagger」，在「Authentication」下用你的用户名/密码调用 POST /Users/AuthenticateByName 获取 AccessToken。
- 基础连通性检查（在 Ubuntu 终端）：
- curl -I http://127.0.0.1:8096/System/Info
- 若通过域名或反代访问，请将 127.0.0.1 替换为你的域名或服务器地址。
二 认证与调用方式
- 请求通用规则：
- 基础 URL：http://<服务器地址>:8096
- 请求头：
- 使用管理员 Key：添加 X-Emby-Authorization: MediaBrowser Token=“你的API Key”
- 使用用户 Token：添加 Authorization: Bearer
- 常见返回：成功通常为 200/201，鉴权失败 401，资源未找到 404。
- 示例 1（管理员 Key，获取服务器信息）：
- curl -H “X-Emby-Authorization: MediaBrowser Token="YOUR_ADMIN_KEY"”
http://127.0.0.1:8096/System/Info
- 示例 2（用户 Token，获取当前用户信息）：
- curl -H “Authorization: Bearer YOUR_USER_TOKEN”
http://127.0.0.1:8096/Users/Me
- 示例 3（管理员 Key，列出所有用户）：
- curl -H “X-Emby-Authorization: MediaBrowser Token="YOUR_ADMIN_KEY"”
http://127.0.0.1:8096/Users
- 示例 4（管理员 Key，触发电影库扫描）：
- curl -X POST
-H “X-Emby-Authorization: MediaBrowser Token="YOUR_ADMIN_KEY"”
http://127.0.0.1:8096/Library/Refresh?api_key=YOUR_ADMIN_KEY
- 示例 5（管理员 Key，按名称搜索电影，返回最多 5 条）：
- curl -G
-H “X-Emby-Authorization: MediaBrowser Token="YOUR_ADMIN_KEY"”
–data-urlencode “searchTerm=Inception”
–data “limit=5”
http://127.0.0.1:8096/Items
- 提示：
- 多数写操作（如刷新库、创建/修改条目）需管理员权限；读取类接口普通用户即可。
- 若你的 Jellyfin 启用了 反向代理/HTTPS，请将 URL 改为 https://你的域名，并确保证书与代理正确转发 /socket 与 /.well-known/ 等路径。
三 常见 API 场景与命令模板
- 媒体库管理
- 获取所有媒体库：curl -H “X-Emby-Authorization: MediaBrowser Token="YOUR_ADMIN_KEY"” http://127.0.0.1:8096/Library/MediaFolders
- 按库 ID 刷新：curl -X POST -H “X-Emby-Authorization: MediaBrowser Token="YOUR_ADMIN_KEY"” http://127.0.0.1:8096/Library/Refresh?itemIds=LIBRARY_ID
- 用户与权限
- 创建用户（管理员）：curl -X POST -H “X-Emby-Authorization: MediaBrowser Token="YOUR_ADMIN_KEY"”
-H “Content-Type: application/json”
-d ‘{“Name”:“apiuser”,“Password”:“StrongPass!”}’
http://127.0.0.1:8096/Users/New
- 设置用户策略（示例：禁止该用户远程访问）：curl -X POST -H “X-Emby-Authorization: MediaBrowser Token="YOUR_ADMIN_KEY"”
-H “Content-Type: application/json”
-d ‘{“IsAdministrator”:false,“EnableRemoteAccess”:false}’
http://127.0.0.1:8096/Users/USER_ID/Policy
- 播放与转码
- 获取播放 URL（需用户 Token）：先获取 ItemId，再访问 /Items/{ItemId}/PlaybackInfo（可带参数如 MaxStreamingBitrate）。
- 获取转码信息：访问 /Items/{ItemId}/PlaybackInfo?MediaSourceId=…&VideoCodec=h264&AudioCodec=aac（返回可用码率、分辨率、容器等）。
- 批量操作建议
- 大量请求时控制并发与间隔，避免触发限流；必要时在脚本中加入重试与退避逻辑。
四 使用脚本与排错要点
- Python 快速示例（获取服务器信息 + 搜索电影）
- pip install requests
- 代码示例：
- import requests
- base = “http://127.0.0.1:8096”
- headers = {“X-Emby-Authorization”: ‘MediaBrowser Token=“YOUR_ADMIN_KEY”’}
- r = requests.get(f"{base}/System/Info", headers=headers, timeout=10)
- print(r.status_code, r.json())
- q = requests.get(f"{base}/Items", headers=headers, params={“searchTerm”: “Inception”, “limit”: 5}, timeout=10)
- print(q.json())
- 常见问题与处理
- 401 Unauthorized：检查 API Key/Token 是否正确、是否过期、是否放在正确请求头。
- 404 Not Found：确认 Base URL 与端口（默认 8096） 正确，且目标资源（如 ItemId、LibraryId）存在。
- 502/504 或连接超时：若使用 Nginx/Apache 反代，确认已正确代理 /socket 与 /.well-known/，并开启 HTTP/2/HTTPS；必要时查看反代与 Jellyfin 日志。
- 局域网正常外网不通：检查路由器端口转发、云服务器安全组、以及反代配置中的 X-Forwarded-Proto/X-Forwarded-Port 头是否正确设置。