参数名	类型	必填	说明
key	string	是	接口调用密钥
action	string	是	search,detail,audio
keyword	string	否
page	string	否

听友听书

接口说明

提供有声书资源的搜索、详情查询及音频获取功能，面向需要接入听书内容服务的开发者。支持通过 Query 参数传入密钥进行鉴权，调用免费且无额外费用。

调用地址

https://api.vsaa.cn/api/book/tingyou/index.php

请求方式

支持 GET 和 POST 两种请求方法。

鉴权说明

调用该接口需传递调用密钥。密钥须通过 URL 查询参数（Query）方式传入，参数名为 key。

请求参数

参数名	类型	必填	说明
key	string	是	接口调用密钥，需通过 Query 参数传递。
action	string	是	指定操作类型，可选值为：`search`（搜索）、`detail`（详情）、`audio`（音频）。
keyword	string	否	搜索关键词。在执行 `search` 操作时，通常需指定该参数以匹配相关有声书资源。
page	string	否	页码。用于分页查询，指定返回结果集中的第几页数据。

成功响应示例

{
  "code": 0,
  "data": {
    "isEnd": false,
    "data": [
      {
        "id": "4167552829",
        "title": "我以鬼眼闯江湖丨头陀渊出品丨古玩鉴宝丨风水秘术丨都市生活丨盗墓",
        "artist": "头陀渊",
        "author": "小九徒",
        "artwork": "https://file.tingyou8.vip/pic/07506ea21e564fc7865e6ae4392901b9.jpg",
        "description": "父母惨死，少年孤悬江湖。十年苦修，练就鬼眼佛手，辨珍宝，破千局。",
        "worksNum": 1289
      },
      {
        "id": "1734590110",
        "title": "相师丨风水秘术丨悬疑灵异丨骨头演播丨多人",
        "artist": "演播人骨头",
        "author": "佚名",
        "artwork": "https://file.tingyou8.vip/pic/7f65e42f77434c448155f44ecba5f09e.jpg",
        "description": "鬼节出生的程逢九胎带奇相胎记九潜龙出，此相贵不可言...",
        "worksNum": 775
      }
    ]
  }
}

响应字段说明

字段	类型	说明
code	int	状态码，`0` 表示请求成功。
data	object	响应数据主体。
data.isEnd	bool	分页结束标志。`false` 表示还有更多数据，`true` 表示当前页为最后一页。
data.data	array	当前页返回的有声书列表。
data.data[].id	string	有声书唯一标识 ID。
data.data[].title	string	有声书标题，通常包含标签、演播信息等分隔内容。
data.data[].artist	string	演播者或制作方名称。
data.data[].author	string	原著作者名称。
data.data[].artwork	string	封面图片 URL 地址。
data.data[].description	string	内容简介，可能包含 `\n` 换行符。
data.data[].worksNum	int	该有声书包含的集数或章节数量。

错误响应示例

当接口请求失败或触发业务限制时，返回 JSON 结构如下：

{
  "code": 0,
  "msg": "密钥错误",
  "errcode": 11002
}

code：固定为 0。
msg：错误描述信息，具体含义见下表。
errcode：业务错误码，用于程序化识别错误类型。

业务错误码说明

以下为完整业务错误码列表，涵盖鉴权、计费、频率限制及接口状态等异常场景：

errcode	含义
11001	未提供调用密钥
11002	密钥错误
11003	密钥已禁用
11004	积分余额不足
11005	请求过于频繁（QPM 限制）
11006	接口维护中
11007	接口已禁用
11008	接口不可用
11009	密钥校验暂不可用
11010	积分系统暂不可用
11011	收费接口须提供有效密钥
11012	鉴权方式错误
11013	接口不存在
11014	***地址无效
11015	***地址不允许
11016	***请求失败
11017	服务暂不可用
11018	请求方式不允许
11019	当前IP不在白名单内
11020	启用出口代理须提供有效密钥
11021	未配置可用出口代理
11022	出口代理不可用
11023	密钥已过期
11024	令牌分配积分不足
11025	该密钥无权调用此接口

调用示例

终端 curl（bash）

使用 GET 方式查询听书内容，需携带密钥参数

curl -G "https://api.vsaa.cn/api/book/tingyou/index.php" \
--data-urlencode "key=YOUR_API_KEY" \
--data-urlencode "action=search" \
--data-urlencode "keyword=鬼眼" \
--data-urlencode "page=1"

PHP

// PHP 示例：使用 cURL 库发送 GET 请求获取听书数据
// 注意：实际调用请将 YOUR_API_KEY 替换为有效密钥

function fetchTingyouBook(string $action, ?string $keyword = null, ?string $page = null): array
{
$baseUrl = 'https://api.vsaa.cn/api/book/tingyou/index.php';
$params = [
'key' => 'YOUR_API_KEY',
'action' => $action,
];

if ($keyword !== null) {
    $params['keyword'] = $keyword;
}

if ($page !== null) {
    $params['page'] = $page;
}

$queryString = http_build_query($params);
$url = $baseUrl . '?' . $queryString;

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200 || $response === false) {
    return ['code' => -1, 'message' => 'Request failed', 'http_code' => $httpCode];
}

$decoded = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    return ['code' => -1, 'message' => 'Invalid JSON response'];
}

return $decoded;

}

// 调用示例：搜索关键词为“鬼眼”的第一页数据
$result = fetchTingyouBook('search', '鬼眼', '1');
print_r($result);

注意事项

密钥安全管理：请务必妥善保管 API 密钥（key）。严禁将密钥硬编码在前端代码、客户端安装包或公开代码仓库中，以防止密钥泄露导致账户被滥用或产生非预期的安全风险。建议仅在后端服务器环境中调用该接口，通过服务端转发数据给前端。
鉴权方式：本接口采用 Query 参数方式进行鉴权，请确保在每次请求的 URL 中正确附带 key 参数。
频率限制：接口限制为每分钟约 60 次调用。请在程序设计中实现请求节流或队列机制，避免因瞬时高频请求触发限流或封禁。
传输协议：请始终使用 HTTPS 协议（https://api.vsaa.cn）进行数据交互，以确保密钥及请求数据在传输过程中的安全性。
参数取值规范：
- action 参数为必填项，取值仅限 search、detail、audio 三者之一，请根据业务逻辑准确传入，避免无效请求。
- keyword 和 page 为可选参数，若不提供，接口将返回默认搜索结果或第一页数据。
- 请确保所有字符串参数在拼接 URL 时进行正确的 URL 编码，防止特殊字符导致解析错误。

免责声明

欢迎使用 万象数据API（以下简称“本平台”，域名为 api.vsaa.cn）。在使用本平台提供的任何接口、数据及相关服务之前，请您务必仔细阅读并充分理解本免责声明的全部内容。您对本平台任何服务的使用，均视为您已阅读、理解并同意本声明的全部条款。

1. 本平台仅提供**技术接口与数据聚合服务**，不存储、不生产、不拥有任何原始数据内容。 2. 本平台所返回的数据均来源于公开网络或第三方接口，仅作**技术学习、研究与交流**之用。 3. 本平台不保证任何接口的**持续可用性、准确性、完整性或及时性**，接口可能因第三方原因随时变更、中断或停止。 1. 使用者应遵守中华人民共和国相关法律法规，以及其所在地的所有适用法律。 2. **禁止**将本平台接口用于任何违法违规用途，包括但不限于： - 侵犯他人知识产权、隐私权或其他合法权益； - 从事网络攻击、数据爬取滥用、恶意刷量等行为； - 传播违法、有害、虚假或不良信息； - 用于任何商业转售、二次分发而未获授权的情形。 3. 使用者应自行承担因使用本平台服务而产生的一切后果与法律责任。 1. 本平台**不收集、不存储**使用者的个人敏感信息。 2. 使用者通过接口提交的查询参数，仅用于当次请求处理，不做持久化留存。 3. 若接口涉及第三方数据，其版权与解释权归原数据方所有，本平台不承担相关争议责任。 1. 本平台以**“现状”**和**“现有”**为基础提供服务，不对服务作出任何明示或暗示的担保。 2. 因使用或无法使用本平台服务而导致的任何**直接、间接、偶然或必然损失**，本平台及其运营者均不承担任何责任。 3. 因不可抗力、网络故障、第三方服务中断、政策调整等原因导致的服务异常，本平台不承担责任。 1. 本平台的接口设计、文档、代码及相关标识，其知识产权归本平台所有。 2. 未经书面许可，任何单位或个人不得复制、修改、传播或用于商业用途。 1. 本平台有权随时修改本免责声明，修改后的内容将在本页面公布，不再另行通知。 2. 使用者应定期查阅本声明，继续使用即视为接受变更后的条款。 1. 本声明的最终解释权归 **万象数据API** 所有。 2. 如您不同意本声明的任何内容，请立即停止使用本平台服务。 3. 如因本声明产生争议，双方应友好协商解决；协商不成的，可提交本平台运营者所在地有管辖权的人民法院裁决。

最后更新日期：2026年10月6日

听友听书

接口信息

请求参数

返回示例

详细文档

听友听书

接口说明

调用地址

请求方式

鉴权说明

请求参数

成功响应示例

响应字段说明

错误响应示例

业务错误码说明

调用示例

终端 curl（bash）

使用 GET 方式查询听书内容，需携带密钥参数

PHP

注意事项

快速上手

在线测试

接口反馈

免责声明

免责声明

推荐接口

Soul