Audiobookshelf API 接口详解与使用指南

概述

Audiobookshelf 是一个开源的音频书籍管理平台，提供了完善的 API 接口供开发者进行二次开发和集成。本文将详细介绍 Audiobookshelf 的 API 接口设计和使用方法，帮助开发者快速上手。

API 基础信息

Audiobookshelf API 采用 OpenAPI 3.0 规范设计，当前版本为 0.1.0。默认开发服务器地址为 http://localhost:3000，采用 Bearer Token 认证方式。

主要功能模块

1. 作者管理接口

作者管理接口提供了对音频书籍作者的增删改查功能：

• 获取作者信息：通过作者 ID 获取详细信息，可选包含该作者的作品和系列信息
• 更新作者信息：支持修改作者名称、描述、图片路径和 ASIN 编号
• 删除作者：从系统中移除作者，同时会从所有关联书籍中删除该作者信息
• 作者图片管理：上传、获取、更新和删除作者图片
• 作者匹配：通过 ASIN 或搜索词将作者与 Audible 数据库匹配，自动补充描述和图片

2. 图书馆管理接口

图书馆是 Audiobookshelf 中的核心概念，用于组织和管理音频书籍：

• 获取所有图书馆：列出服务器上的所有图书馆
• 创建新图书馆：需要提供名称和文件夹路径等基本信息
• 图书馆设置：可配置显示顺序、图标、媒体类型等属性

3. 电子邮件功能接口

Audiobookshelf 提供了将电子书发送到电子阅读器的功能：

• 获取/更新邮件设置：配置 SMTP 服务器等发送参数
• 测试邮件发送：验证邮件配置是否正确
• 管理电子阅读器设备：维护可接收电子书的设备列表
• 发送电子书到设备：将指定图书馆项目发送到已配置的设备

4. 系列管理接口

系列管理接口允许对音频书籍系列进行操作：

• 获取系列信息
• 更新系列元数据
• 管理系列封面图片

5. 播客管理接口

播客相关功能包括：

• 播客订阅管理
• 单集下载控制
• 播放进度同步

接口使用示例

获取作者信息

GET /api/authors/{id}?include=items,series
Authorization: Bearer {token}

响应示例：

{
  "id": "auth_123",
  "name": "J.K. Rowling",
  "description": "British author best known for the Harry Potter series...",
  "imagePath": "/author_images/auth_123.jpg",
  "items": [
    {
      "id": "lib_456",
      "title": "Harry Potter and the Philosopher's Stone"
    }
  ],
  "series": [
    {
      "id": "ser_789",
      "name": "Harry Potter"
    }
  ]
}

创建新图书馆

POST /api/libraries
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Fantasy Books",
  "folders": ["/mnt/audiobooks/fantasy"],
  "mediaType": "book",
  "icon": "fantasy"
}

最佳实践

1. 错误处理：所有接口都遵循标准 HTTP 状态码，404 表示资源不存在，403 表示权限不足等

2. 批量操作：部分接口支持批量操作，如同时更新多个电子阅读器设备

3. 图片处理：作者和系列图片接口支持动态调整大小和格式转换

4. 数据匹配：利用 Audible 匹配功能可以自动补充元数据，减少手动输入

5. 安全考虑：所有敏感操作都需要 Bearer Token 认证

总结

Audiobookshelf 提供了完善的 API 接口，覆盖了音频书籍管理的各个方面。通过合理使用这些接口，开发者可以构建自己的客户端应用，或者将 Audiobookshelf 集成到现有系统中。本文介绍了主要接口的功能和使用方法，更多细节可以参考完整的 OpenAPI 规范文档。