YoutubeDL-Material 项目 API 接口详解

项目概述

YoutubeDL-Material 是一个基于 Web 的视频下载和管理平台，提供了一套完整的 RESTful API 接口，允许开发者通过编程方式与系统交互。本文将详细介绍该项目的 API 接口设计和使用方法。

API 认证方式

YoutubeDL-Material 提供了两种认证方式：

1. API Key 认证：

   • 在设置菜单中生成 API Key
   • 请求时需附加 ?apiKey=YOUR_API_KEY 参数
   • 适用于单用户模式

2. JWT Token 认证（多用户模式）：

   • 首先通过 /api/auth/login 端点获取 JWT Token
   • 请求时需同时附加 API Key 和 JWT Token：?apiKey=API_KEY&jwt=JWT_TOKEN
   • 适用于多用户环境，可区分不同用户的操作

核心 API 接口分类

1. 下载管理接口

/api/downloadFile

• 功能：下载指定 URL 的视频文件
• 请求方法：POST
• 请求体：包含下载 URL 和参数的 JSON 对象
• 响应：返回下载状态和结果信息
• 特点：会应用全局下载参数（如果存在）

/api/generateArgs

• 功能：生成下载参数预览
• 请求方法：POST
• 用途：在实际下载前预览将使用的下载参数
• 响应：返回生成的参数列表

2. 文件管理接口

文件获取类接口

• /api/getMp3s：获取所有 MP3 音频文件和音频播放列表
• /api/getMp4s：获取所有 MP4 视频文件和视频播放列表
• /api/getAllFiles：获取所有文件和播放列表
• /api/getFile：根据 UID 获取特定文件信息

文件操作类接口

• /api/updateFile：更新文件元数据
• /api/deleteMp4：删除 MP4 文件
• /api/deleteFile：删除文件
• /api/deleteAllFiles：删除所有文件

文件共享接口

• /api/enableSharing：启用文件共享
• /api/disableSharing：禁用文件共享

3. 订阅管理接口

订阅操作接口

• /api/subscribe：订阅频道或播放列表
• /api/unsubscribe：取消订阅
• /api/checkSubscription：检查订阅更新
• /api/cancelCheckSubscription：取消订阅检查

订阅内容管理

• /api/downloadVideosForSubscription：手动下载订阅内容
• /api/deleteSubscriptionFile：删除订阅中的特定文件
• /api/getSubscription：获取订阅详情
• /api/getSubscriptions：获取所有订阅

4. 播放列表管理接口

播放列表操作

• /api/createPlaylist：创建播放列表
• /api/getPlaylist：获取播放列表详情
• /api/updatePlaylist：更新播放列表
• /api/deletePlaylist：删除播放列表
• /api/addFileToPlaylist：添加文件到播放列表

5. 其他实用接口

• /api/rss：生成 RSS 订阅源
• /api/incrementViewCount：增加文件查看计数
• /api/downloadFileFromServer：从服务器下载已下载的文件

接口设计特点

1. RESTful 风格：所有接口遵循 REST 设计原则，使用标准 HTTP 方法和状态码

2. 统一响应格式：

   • 成功响应通常包含 SuccessObject 结构
   • 错误响应包含明确的状态码和错误信息

3. 批量操作支持：如 deleteAllFiles 等接口支持批量操作

4. 文件类型区分：明确区分音频(MP3)和视频(MP4)文件操作

5. 订阅自动化：订阅相关接口支持自动检查和下载新内容

最佳实践建议

1. 错误处理：始终检查响应状态码，特别是 401(未授权)和 500(服务器错误)

2. 批量操作谨慎使用：如 deleteAllFiles 等接口应谨慎调用

3. 订阅管理：合理使用 checkSubscription 和 downloadVideosForSubscription 接口组合

4. 文件共享：通过 enableSharing/disableSharing 控制文件访问权限

5. 元数据管理：利用 updateFile 和 updatePlaylist 维护文件信息

总结

YoutubeDL-Material 的 API 设计全面覆盖了视频下载、管理和分享的各个环节，提供了灵活而强大的编程接口。通过合理使用这些接口，开发者可以构建自定义的视频管理解决方案，或将其集成到现有系统中。