开发者文档
概览
XiaoshuoHub 提供两个只读接口:检索作品、按 ID 取作品详情。返回 JSON,编码 UTF-8。基础地址:
https://api.xiaoshuohub.com/v1数据来源与「综合人气」的口径见关于本站。
额度
| 调用方式 | 每天 | 计数依据 |
|---|---|---|
| 不带令牌 | 200 次 | IP |
| 站内登录用户 / 开发者应用令牌 | 1000 次 | 账号 |
- 按滚动 24 小时计算,不是自然日;同一账号下的多个应用共用额度。
- 每次响应带
Ratelimit-Limit(上限)和Ratelimit-Remaining(剩余)头。 - 超额返回
429,Retry-After头给出需等待的秒数。 - 搜索最多翻到第 250 条结果,
total最大为 250。
创建应用
- 打开开发者门户 https://api.xiaoshuohub.com/apps/developer/。
- 点「Login」,选 keycloak,用本站账号登录(与搜索、评论是同一个账号;没有账号可在登录页注册)。
- 进入「Apps」,新建应用:填写名称和网址,权限(scopes)勾选
default——不勾的话令牌调用会被当作匿名,按 IP 计 200 次。 - 打开应用详情,得到
App Key和App Secret。Secret 等同密码,只放在服务端,不要写进前端代码或公开仓库。 - 在门户里可以删除应用;「Log」页可以查看调用记录。
认证
用 App Key 和 App Secret 以 HTTP Basic 换取访问令牌(OAuth2 client credentials):
curl -X POST https://api.xiaoshuohub.com/authorization/token \
-u "APP_KEY:APP_SECRET" \
-d grant_type=client_credentials返回:
{
"access_token": "eyJ0eXAiOiJKV1Qi…",
"token_type": "bearer",
"expires_in": 172800,
"refresh_token": "8b5de6c56a409b47e289-…",
"scope": "authorization,default"
}之后每个请求带上 Authorization: Bearer <access_token>。令牌有效期 48 小时(expires_in 秒),过期前可以用 refresh_token 续期,或者直接重新申请:
curl -X POST https://api.xiaoshuohub.com/authorization/token \
-u "APP_KEY:APP_SECRET" \
-d grant_type=refresh_token \
-d refresh_token=REFRESH_TOKEN不带令牌也能调用,按匿名额度计算。
GET /v1/search
按书名、作者、简介检索作品,可叠加筛选。所有参数都可选。
| 参数 | 类型 | 说明 |
|---|---|---|
q | 字符串 | 关键词,匹配书名、作者、简介;空格分隔的每个词按短语匹配 |
author | 字符串 | 作者名,整串精确匹配 |
tags | 字符串 | 标签,逗号分隔,多个值须同时满足 |
sites | 字符串 | 平台名(如 起点中文网),逗号分隔,多个值须同时满足 |
category | 字符串 | 平台原分类名 |
genre | 字符串 | 统一分类 slug,如 xuanhuan,完整列表见小说分类 |
status | 枚举 | ongoing 连载 | completed 完结 |
words_min / words_max | 整数 | 字数下限 / 上限 |
updated_after | 日期 | YYYY-MM-DD,只返回该日之后更新的作品 |
sort | 枚举 | 省略按相关度;heat 综合人气 | updated 最近更新 | words 字数 |
page | 整数 | 页码,从 1 开始,每页 20 条;超过第 250 条(page ≥ 14)返回 400 |
curl -H "Authorization: Bearer $TOKEN" \
"https://api.xiaoshuohub.com/v1/search?genre=xuanhuan&status=completed&sort=heat"const url = new URL("https://api.xiaoshuohub.com/v1/search");
url.search = new URLSearchParams({ q: "凡人修仙传", sort: "heat" });
const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
if (res.status === 429) console.log("等待秒数", res.headers.get("Retry-After"));
const data = await res.json();响应:
{
"total": 250,
"page": 1,
"pages": 13,
"items": [
{
"id": 549460,
"title": "凡人修仙传",
"title_html": "<mark>凡人修仙传</mark>",
"author": "忘语",
"category": "古典仙侠",
"status": "completed",
"word_count": 7183000,
"intro_html": "已改编影视,由杨洋主演。…",
"sites": ["书旗小说"],
"cover": "https://…/11139534078_sa.jpg"
}
]
}title_html 和 intro_html 已整体做过 HTML 转义,只有命中关键词处包着 <mark>,可以直接当 HTML 插入。intro_html 是截断后的摘要。作品页地址为 https://www.xiaoshuohub.com/book/{id}/。
GET /v1/works/{id}
按作品 ID(纯数字)返回详情,字段与作品页一致。
curl -H "Authorization: Bearer $TOKEN" https://api.xiaoshuohub.com/v1/works/471152| 字段 | 说明 |
|---|---|
id title author author_id | 作品 ID、书名、作者、作者页 ID(/author/{author_id}/) |
intro | 完整简介,纯文本,换行为 \n |
cover | 封面图地址 |
genre | 统一分类 {"slug","name"},未归类为 null |
category | 平台原分类 {"site_name","names":[…]} |
tags tag_pages | 全部标签;其中有标签页(/tag/{name}/)的那部分 |
status word_count chapter_count | 连载状态、字数、章节数 |
latest_chapter latest_update | 最新章节名与更新时间(ISO 8601,UTC) |
heat rank top_pct | 综合人气(0–100)、全站排名、前百分之几;无人气时为 null |
sources | 各平台记录:site、site_name、官方链接 url、rating、metrics[]{label,value}、该平台内人气 heat |
similar author_works | 相似作品、同作者其他作品,元素为 {id,title,author} |
as_of | 数据抓取时间 |
错误码
出错时统一返回 {"error": "说明"}:
| 状态码 | 含义 |
|---|---|
400 | 翻页超过第 250 条:{"error":"最多返回前 250 条结果"} |
404 | 作品不存在:{"error":"作品不存在"} |
429 | 超出每日额度,按 Retry-After 等待 |
502 | 检索服务暂时不可用:{"error":"检索服务不可用"},稍后重试 |
使用要求
展示数据时须注明来源「XiaoshuoHub」并链接本站;不得绕过限速、批量抓取后再分发或冒充本站。完整条款见用户协议 · 开发者 API。