小说库接口

小说库对外开放的接口都汇总在这里。鉴权、签名、统一响应信封与鉴权层错误码见 开发者文档；本页只列各端点的字段与业务规则。更多小说库接口将陆续开放，届时在本页新增小节，无需另找文档。

所有接口挂在子域 https://openapi.dracalon.com，路径形如 /v1/...，Content-Type: application/json。签名头（X-Access-Key / X-Timestamp / X-Nonce / X-Signature 等）与 canonical 串规则见 开发者文档 · 鉴权与签名。

推荐小说 · POST /v1/novel/recommend

代凭证绑定会员提交一条小说推荐，与该会员在网页提交推荐完全等价——同一套后台审核流程、通知与统计，调用方无法冒用其他会员身份。需要凭证被授权 novel.recommend 接口。

业务规则

• 归属凭证绑定会员：推荐记录挂在该 AccessKey 绑定的会员名下。多个凭证绑定同一会员则共享下列配额。
• 每日配额：按绑定会员计，每天最多 5 条（含待审 / 通过 / 驳回，撤回不占额）。超出返回 今日推荐次数已达上限，请明天再来。
• 防重复：同一 source_url 若已在审核队列、已存在于站内、或在本人驳回冷静期（默认 7 天）内，会被拒绝。
• 先提交后审核：成功只代表进入待审核（status=0），是否上架由运营审核决定，结果通过站内信 + 邮件通知绑定会员。
• 功能开关：若后台关闭了小说推荐，返回 小说推荐功能暂未开放。

请求字段

字段	类型	必填	说明
title	string	是	书名，1–200 字符
source_url	string	是	作品原文链接，http(s):// 开头，≤500，全站唯一
intro	string	否	推荐理由 / 简介，选填；若填写则 10–5000 字符
author	string	否	作者，≤120
cover_image	string	否	封面：http(s) 绝对 URL 或服务端上传返回的 / 开头相对路径，≤500
category_id	int	否	小说分类 ID（站内分类法 ID）
tag_ids	int[]	否	标签 ID 数组，最多 20，须为站内已存在标签
publish_status	int	否	连载状态：0未知 1连载 2完结 3断更 4暂停（缺省 0，后续同步可能修正）
word_count	int	否	字数，≥0

请求示例

{
  "title": "测试小说",
  "author": "某位作者",
  "source_url": "https://www.example.com/book/12345",
  "intro": "一句话推荐理由，至少十个字符的简介内容。",
  "publish_status": 1,
  "tag_ids": [3, 7]
}

成功响应

{
  "code": 1,
  "msg": "Submit success",
  "time": 1719200000,
  "data": { "id": "1024", "status": 0, "create_time": 1719200000, "request_id": "..." }
}

status=0 表示待审核（PENDING）。任意响应都带 X-Request-Id 响应头，与 data.request_id 一致，便于排障。

常见业务错误（code=0）

msg	触发
书名不能为空 / 推荐理由/简介长度必须在 10-5000 个字符之间 等	字段校验未过
作品原文链接必须以 http:// 或 https:// 开头	source_url 协议非法
你已推荐过该作品，请耐心等待审核 / 该作品已在审核队列中，请勿重复推荐	source_url 防重
该作品已存在于站内	该链接已入库
今日推荐次数已达上限，请明天再来	超每日配额
部分小说标签不存在	tag_ids 含非法 ID

以下 4 个接口均为半开放接口（need_auth=1 且 auth_scope=1）——任意持有有效凭证的调用方均可直接调用，无需逐接口申请授权；签名、时间戳/nonce 防重放、IP 白名单、限流仍照常执行，规则见 开发者文档。

小说列表 · GET /v1/novel/list

分页拉取小说列表，可按分类 / 标签 / 篇幅 / 平台 / 关键词筛选。

请求参数

参数	必填	说明
category_code	否	分类 code；解析不到已启用分类时返回空结果集（不是错误）
tag_code / tag_codes	否	标签 code，多个之间 AND 交集；逗号分隔字符串 a,b 或数组，最多 8 个
length	否	篇幅：short 短篇 / long 长篇 / epic 史诗
platform	否	平台 code（单选，取值见下方 novel.taxonomy 的 platforms）；非法值视同未筛选
keyword	否	关键词，≤50 字，命中书名 / 作者 / 标签名
order	否	排序：popularity 热度（默认）/ latest 最新 / score 评分
page	否	页码，1–1000，默认 1
limit	否	每页条数，1–60，默认 20

响应字段

data = {items[], total, page, limit}，items 每项：

字段	类型	说明
id	string	小说 ID（雪花 ID，以字符串下发避免 JS 精度丢失，下同）
slug	string	详情接口用的 slug
title	string	书名
author	string|null	作者，可空
cover_image	string|null	封面地址
intro	string|null	简介（纯文本）
category_id	string	分类 ID，"0" = 未分类
platforms	string[]	平台 code 数组
publish_status	int	连载状态：0 未知 / 1 连载 / 2 完结
word_count	int	字数
score	float|null	站内用户评分均值（0–10 制），无评分为 null
score_count	int	评分人数
popularity	int	站内热度值
favorite_count	int	收藏数
comment_count	int	评论数
category	object|null	{id, name, code}（id 为字符串），未分类为 null
tags	object[]	[{id, name, code}]（id 为字符串）

示例响应

{
  "code": 1,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "1024",
        "slug": "dou-po-cang-qiong",
        "title": "斗破苍穹",
        "author": "天蚕土豆",
        "cover_image": "/uploads/novel/1024.jpg",
        "intro": "斗气大陆，弱肉强食……",
        "category_id": "2",
        "platforms": ["qidian"],
        "publish_status": 2,
        "word_count": 5200000,
        "score": 9.0,
        "score_count": 320,
        "popularity": 9821,
        "favorite_count": 1500,
        "comment_count": 210,
        "category": { "id": "2", "name": "东方玄幻", "code": "eastfantasy" },
        "tags": [{ "id": "11", "name": "东方龙", "code": "dragon-eastern" }]
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20,
    "request_id": "..."
  }
}

注意事项

• 无 per-user 字段：不下发 is_favorited 等站内登录态字段，小说本身也没有 i18n，字段单语中文。
• 参数越界（page / limit / tag_codes 超 8 个等）会被后端钳制到合法区间，不报错。
• 业务错误统一 {code:0, msg} 信封。

小说详情 · GET /v1/novel/detail

按 slug 查询单本小说详情。

请求参数

参数	必填	说明
slug	是	小说 slug

响应字段

在列表条目字段基础上追加：

字段	类型	说明
intro_html	string|null	已净化的简介 HTML，可空
sources	object[]	公开来源链接，[{url, label}]
create_time	int	入库时间，秒级时间戳
update_time	int	最近更新时间，秒级时间戳

注意事项

• 只返回已上架小说（status=1）；未上架或不存在一律返回业务错误（code=0），不区分"不存在"与"未上架"，防止外部探测草稿是否存在。
• 不计入站内浏览 / 热度统计——调用本接口不会推高该书的 popularity，与前台用户访问详情页的计数路径相互独立，避免被当作刷热度的手段。

小说分类法 · GET /v1/novel/taxonomy

一次性拉取分类法全量数据，供客户端本地构建筛选 UI（分类 / 标签 / facet 分组 / 平台），无需分别调用四个接口。

请求参数

无。

响应字段

data = {categories[], tags[], facets[], platforms[]}：

字段	类型	说明
categories	object[]	题材主分类，{id, parent_id, name, code, description}
tags	object[]	全部启用标签（含未分组的旧标签），{id, name, code}
facets	object[]	按组下发的筛选标签组，{facet, label, items:[{id, name, code}]}；固定 4 组，顺序：dragon 龙设 / plot 走向 / romance 情感 / setup 设定
platforms	object[]	平台清单，{code, name}

示例响应（节选）

{
  "code": 1,
  "msg": "success",
  "data": {
    "categories": [
      { "id": "2", "parent_id": "0", "name": "东方玄幻", "code": "eastfantasy", "description": "仙侠修真 / 东方神话" }
    ],
    "tags": [
      { "id": "11", "name": "东方龙", "code": "dragon-eastern" }
    ],
    "facets": [
      { "facet": "dragon", "label": "龙设", "items": [{ "id": "11", "name": "东方龙", "code": "dragon-eastern" }] }
    ],
    "platforms": [
      { "code": "qidian", "name": "起点中文网" }
    ],
    "request_id": "..."
  }
}

注意事项

• 与第一方 GET /api/novel/{categories,tags,facets,platforms} 共享同一份缓存（SwrCache + NovelTaxonomyCacheBuster 失效机制），数据口径完全一致。

随机小说 · GET /v1/novel/random

按筛选条件随机抽取若干本小说，适合"猜你想读" / 首页随机推荐位等场景。

请求参数

复用 novel.list 的全部筛选维度（category_code / tag_code / tag_codes / length / platform / keyword），忽略 order / page / limit；额外接受：

参数	必填	说明
count	否	抽取数量，1–5，默认 1

响应字段

data = {items[]}，items 字段与 novel.list 完全一致（见上）；可用小说不足 count 时按实际数量返回，不报错。

注意事项

• 结果不缓存——每次调用都是一次新的随机抽取，不走 SwrCache。
• 筛选条件校验规则与 novel.list 一致（非法值降级/钳制，不报错）。