PeerTube API 全面解析：从入门到精通

一、PeerTube API 概述

PeerTube 是一个基于 ActivityPub 协议的去中心化视频平台，其 API 采用 RESTful 架构设计，遵循 OpenAPI 3.0 规范。最新版本为 7.1.0，采用 AGPLv3.0 开源协议。

主要特点

• 完全兼容 OpenAPI Generator，可自动生成多种语言的客户端 SDK
• 支持 Python、Go、Kotlin 等主流语言的客户端
• 完善的错误处理机制，符合 RFC7807 标准
• 内置完善的速率限制机制
• 支持 CORS 跨域访问

二、认证与权限系统

认证机制

PeerTube 采用 OAuth2 认证方式，用户通过访问令牌进行身份验证。需要注意的是：

• 同一时间只能使用一个有效访问令牌
• 令牌通过用户账户生成

角色权限

PeerTube 采用三级角色权限体系：

1. 管理员(Administrator)：拥有最高权限，可管理整个实例
2. 版主(Moderator)：负责内容审核和管理
3. 普通用户(User)：基础用户权限

三、错误处理规范

PeerTube API 采用标准 HTTP 状态码结合 RFC7807 规范的错误响应体：

{
  "detail": "错误详情",
  "docs": "相关文档链接",
  "status": 状态码,
  "title": "错误标题",
  "type": "错误类型标识"
}

错误类型

1. 参数验证错误：400 Bad Request

   • 包含详细的参数验证失败信息
   • 标注参数位置(params/body/header等)
   • 提供错误值和错误原因

2. 资源未找到：404 Not Found

3. 权限不足：403 Forbidden

4. 速率限制：429 Too Many Requests

四、速率限制机制

PeerTube 对所有 API 端点实施速率限制，管理员可自定义限制规则：

端点	请求次数	时间窗口
通用API	50次	10秒
令牌获取	15次	5分钟
用户注册	2次	5分钟
验证邮件	3次	5分钟

速率限制响应头

• X-RateLimit-Limit：最大请求数
• X-RateLimit-Remaining：剩余请求数
• X-RateLimit-Reset：重置时间戳
• Retry-After：重试等待时间(秒)

五、核心功能模块

1. 视频管理

• 视频上传(支持断点续传)
• 视频导入(支持URL、P2P链接、资源文件)
• 视频转码
• 视频统计
• 视频下载
• 视频播放列表

2. 用户与账户

• 用户注册与认证
• 用户数据导出/导入
• 订阅管理
• 观看历史
• 通知系统

3. 频道与评论

• 视频频道管理
• 评论系统(支持多级回复)
• 频道同步(跨平台)

4. 搜索功能

• 本地视频/频道搜索
• 联邦网络搜索
• 高级搜索条件

5. 实例管理

• 实例配置
• 实例间关注管理
• 冗余策略
• 插件系统

六、视频上传详解

PeerTube 支持两种上传模式：

1. 传统上传：单次请求完成整个文件上传

   • 适合小文件
   • 实现简单

2. 可恢复上传：分块上传，支持断点续传

   • 适合大文件(推荐>100MB)
   • 网络不稳定时优势明显
   • 节省带宽，提高可靠性

视频导入方式

1. URL导入：支持 youtube-dl 兼容的网站
2. P2P链接导入：支持分布式资源
3. 资源文件导入：支持资源文件

七、开发建议

1. 认证最佳实践

   • 妥善保管访问令牌
   • 实现令牌刷新机制
   • 处理401未授权错误

2. 错误处理

   • 解析错误响应体获取详细信息
   • 对速率限制实现自动退避
   • 验证错误提供用户友好的提示

3. 性能优化

   • 对大文件使用可恢复上传
   • 合理利用缓存
   • 遵守速率限制

4. 联邦功能

   • 理解 ActivityPub 协议
   • 处理跨实例数据同步
   • 考虑实例间冗余策略

八、总结

PeerTube API 提供了完整的去中心化视频平台功能接口，开发者可以利用这些接口构建丰富的客户端应用或集成服务。其完善的认证机制、清晰的错误处理和灵活的速率限制为开发者提供了良好的开发体验。特别值得注意的是其对联邦网络的支持，这使得基于 PeerTube 的应用可以天然具备去中心化特性。