↓ 跳过正文

开发者文档

概览

XiaoshuoHub 提供两个只读接口:检索作品、按 ID 取作品详情。返回 JSON,编码 UTF-8。基础地址:

https://api.xiaoshuohub.com/v1

数据来源与「综合人气」的口径见关于本站。

额度

调用方式每天计数依据
不带令牌200 次IP
站内登录用户 / 开发者应用令牌1000 次账号
  • 按滚动 24 小时计算,不是自然日;同一账号下的多个应用共用额度。
  • 每次响应带 Ratelimit-Limit(上限)和 Ratelimit-Remaining(剩余)头。
  • 超额返回 429,Retry-After 头给出需等待的秒数。
  • 搜索最多翻到第 250 条结果,total 最大为 250。

创建应用

  1. 打开开发者门户 https://api.xiaoshuohub.com/apps/developer/。
  2. 点「Login」,选 keycloak,用本站账号登录(与搜索、评论是同一个账号;没有账号可在登录页注册)。
  3. 进入「Apps」,新建应用:填写名称和网址,权限(scopes)勾选 default——不勾的话令牌调用会被当作匿名,按 IP 计 200 次。
  4. 打开应用详情,得到 App Key 和 App Secret。Secret 等同密码,只放在服务端,不要写进前端代码或公开仓库。
  5. 在门户里可以删除应用;「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

不带令牌也能调用,按匿名额度计算。

按书名、作者、简介检索作品,可叠加筛选。所有参数都可选。

参数类型说明
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。