API文档

/api/tags

获取标签信息,支持多种参数筛选和字段定制。

请求方式GET /api/tags
请求参数
参数类型必填说明
hotint返回最热门的前N个标签(按作品数量排序)
randomint随机返回N个标签
fieldsstring指定返回字段,逗号分隔,如fields=name,alias
novel_titlestring根据作品名返回该作品的标签
idint标签ID,返回单个标签对象
返回字段
字段类型说明
idint标签ID
namestring标签名称
aliasstring标签别名(用于URL)
abbrstring拼音首字母缩写
descriptionstring标签描述
novel_countint该标签下作品数量
示例
GET /api/tags?id=679

返回:
{
  "id": 679,
  "name": "都市",
  "alias": "dushi",
  "abbr": "ds",
  "description": "都市题材相关小说",
  "novel_count": 42
}

/api/author

获取作者信息,支持按ID或笔名查询。

请求方式GET /api/author
请求参数
参数类型必填说明
idint作者ID,精确查找
pen_namestring作者笔名,精确查找
deadint是否只返回已去世作家,1为只返回已去世,0为只返回在世,不传为全部
pageint页码,默认1
page_sizeint每页数量,默认24
分页示例:
GET /api/author?dead=1&page=1&page_size=12 返回第1页的已去世作家,每页12个。
GET /api/author?dead=0&page=2&page_size=10 返回第2页的在世作家,每页10个。
GET /api/author?page=1&page_size=20 返回全部作家第1页,每页20个。
返回字段
字段类型说明
idint作者ID
pen_namestring笔名
aliasstring别名/马甲
real_namestring本名
nationalitystring国籍
genderstring性别
ethnicitystring民族
ageint年龄
provincestring省份
identitystring身份/职业
signed_websitestring签约网站
biostring个人简介
avatarobject头像对象,含 String(头像URL)和 Valid(是否有效)
is_deadbool是否已去世
created_atstring创建时间(ISO8601)
updated_atstring更新时间(ISO8601)

/api/novel

获取小说列表或单本详情,支持多种筛选、字段定制和分页。

请求方式GET /api/novel
请求参数
参数类型必填说明
idint小说ID,返回单本详情,和分页参数互斥
user_idint用户ID,返回该用户最近阅读小说(配合 fields=note 返回读书笔记)
pageint页码,默认1
sizeint每页数量,默认20,最大100
fieldsstring只返回指定字段,逗号分隔,如 fields=title,cover
excludestring排除指定字段,逗号分隔,如 exclude=summary
authorstring作家笔名筛选
author_idint作家ID筛选
tagstring标签别名筛选
keywordstring关键字模糊搜索
randomint/bool1为随机返回N本小说(配合size)
guestint以该作品ID为基础,优先推荐与其标签有重叠的小说(重叠越多越优先,部分标签重叠也可推荐),不足时随机补齐,默认返回6本
sortstring排行榜/排序类型,支持:
  • read 按已读人数排行
  • rating 按评分排行(只返回有评分的作品)
  • word_count 按字数排行
  • first_order 按首订排行
  • average_sub 按均订排行(只返回有均订数据的作品)
  • max_sub 按高订排行(只返回有高订数据的作品)
  • achievements 按盟主排行
  • date 按发布日期/完结日期排序(配合 date_type
orderstring排序方式,asc(升序)或 desc(降序),默认 desc
date_typestring"发布" 或 "完结",配合 sort=dateyear_month 使用
year_monthstring年月筛选,如 202405,配合 date_type 使用
year_liststring"发布" 或 "完结",返回有数据的年份数组
badge_idint徽章ID,筛选拥有该徽章的所有作品,支持分页和字段过滤
如传入 id 参数,则返回该小说的完整详情对象(含 badges、tags、pen_name、author_alias、author_realname、complete_date、first_order、achievements 等),不分页。
返回字段
字段类型说明
idint小说ID
titlestring书名
aliasstring别名/短链
author_idint作者ID
pen_namestring作者笔名
author_aliasstring作者马甲
author_realnamestring作者本名
genrestring题材分类
word_countint字数
statusstring连载状态
publish_datestring首发日期(YYYY-MM-DD)
complete_datestring完结日期(YYYY-MM-DD)
summarystring简介(可用 exclude 排除)
coverobject封面对象,含 String(图片URL)和 Valid
original_sitestring首发站点名称,如"起点中文网"
read_linkstring试读链接URL,若有则页面显示"试读"按钮
avg_ratingfloat平均评分
rating_countint评分人数
is_publicbool是否公开
created_atstring创建时间(ISO8601)
updated_atstring更新时间(ISO8601)
badgesarray获得的徽章(对象数组)
tagsarray标签(对象数组)
first_orderint首订人数
average_subint均订(平均订阅数)
max_subint高订(最高订阅数)
achievementsint盟主/成就数字
notestring用户读书笔记(需带 user_id 且 fields 包含 note)
分页与返回结构
{
  "page": 1,
  "size": 20,
  "total": 123,
  "novels": [
    {
      "id": 1,
      "title": "小说名",
      "cover": {"String": "/cover/xxx.jpg", "Valid": true},
      "status": "连载中",
      "avg_rating": 8.9,
      "pen_name": "作家名",
      "word_count": 123456,
      "publish_date": "2020-01-01",
      "first_order": 100,
      "average_sub": 80,
      "max_sub": 120,
      "achievements": 5,
      "note": "用户读书笔记内容"
      // ... 其它字段 ...
    }
  ]
}
单本详情返回结构
{
  "novel": {
    "id": 123,
    "title": "三体",
    "alias": "3body",
    "author_id": 1,
    "pen_name": "刘慈欣",
    "author_alias": "大刘",
    "author_realname": "刘慈欣",
    "genre": "科幻",
    "word_count": 300000,
    "status": "已完结",
    "publish_date": "2008-01-01",
    "complete_date": "2010-01-01",
    "summary": "黑暗森林法则...",
    "cover": {"String": "/cover/3body.jpg", "Valid": true},
    "original_site": "起点中文网",
    "read_link": "https://www.qidian.com/book/123",
    "avg_rating": 9.2,
    "rating_count": 10000,
    "is_public": true,
    "created_at": "2008-01-01T00:00:00Z",
    "updated_at": "2024-06-07T12:00:00Z",
    "badges": [ { "id": 1, "name": "金奖" } ],
    "tags": [ { "id": 2, "name": "科幻" } ],
    "first_order": 100,
    "average_sub": 80,
    "max_sub": 120,
    "achievements": 5
  }
}
返回结构补充
  • 年份列表year_list=发布year_list=完结
    {
      "years": [2020, 2021, 2022, 2023, 2024]
    }
  • 阅读人数排行sort=read
    {
      "page": 1,
      "size": 20,
      "total": 100,
      "novels": [
        {
          "id": 1,
          "title": "小说名",
          "cover": "...",
          "status": "连载中",
          "pen_name": "作家名",
          "read_count": 1234
        }
      ]
    }
  • 年月筛选date_typeyear_month 搭配)
    {
      "page": 1,
      "size": 20,
      "total": 10,
      "novels": [
        {
          "title": "小说名",
          "publish_date": "2024-05-01",
          "complete_date": "",
          "status": "连载中",
          "pen_name": "作家名",
          "cover": "..."
        }
      ]
    }
更多示例
  • 评分排行:
    GET /api/novel?sort=rating&order=desc&page=1&size=10&fields=title,cover,avg_rating,rating_count
  • 字数排行:
    GET /api/novel?sort=word_count&order=desc&page=1&size=10&fields=title,cover,word_count
  • 首订排行:
    GET /api/novel?sort=first_order&order=desc&page=1&size=10&fields=title,cover,first_order
  • 盟主排行:
    GET /api/novel?sort=achievements&order=desc&page=1&size=10&fields=title,cover,achievements
  • 高订排行:
    GET /api/novel?sort=max_sub&order=desc&page=1&size=10&fields=title,cover,max_sub
  • 按发布日期排序:
    GET /api/novel?sort=date&date_type=发布&order=desc&page=1&size=10&fields=title,cover,publish_date
  • 按完结日期排序:
    GET /api/novel?sort=date&date_type=完结&order=desc&page=1&size=10&fields=title,cover,complete_date
    只返回有有效完结日期的小说。
  • 获取有数据的年份:
    GET /api/novel?year_list=发布GET /api/novel?year_list=完结
  • 猜你喜欢:
    GET /api/novel?guest=530&fields=title,cover
  • 均订排行:
    GET /api/novel?sort=average_sub&order=desc&page=1&size=10&fields=title,cover,average_sub
注意事项
  • fieldsexclude 可灵活组合,建议前端只请求所需字段,提升性能。
  • cover 字段为对象,需取 String 属性为图片URL。
  • badgestags 字段为对象数组,结构见实际返回。
  • note 字段仅在带 user_idfields 包含 note 时返回。
  • publish_datecomplete_date 格式为 YYYY-MM-DD,如无则为空字符串。
  • first_orderaverage_submax_subachievements 字段为数字,分别表示首订、均订、高订和盟主数。
  • date_type=完结 时,接口只返回有有效完结日期(非空且大于1900-01-01)的小说,分页和总数也基于此过滤。

/api/coin

获取金币交易记录、金币排行榜。需登录。

请求方式GET /api/coin
请求参数
参数类型必填说明
pageint页码,默认1
page_sizeint每页数量,默认20,最大100
allint1为查询所有用户的金币记录(需有权限),否则只查当前用户
topint1为返回金币排行榜(分页),否则返回金币记录
返回字段
字段类型说明
recordsarray金币交易记录数组(非排行榜模式)
rankingsarray金币排行榜数组(排行榜模式)
totalint总记录数
pageint当前页码
total_pagesint总页数
金币记录对象字段
字段类型说明
idint记录ID
user_idint用户ID
usernamestring用户名
amountint变动金额(正为收入,负为支出)
typestring变动类型(如signin、game_reward等)
descriptionstring描述
related_idobject关联ID(如游戏/导出等)
created_atstring创建时间(ISO8601)
排行榜对象字段
字段类型说明
user_idint用户ID
usernamestring用户名
avatar_pathstring头像URL(如为空请用 /api/avatar?size=28&seed=用户名 兜底)
coin_balanceint金币余额
rankint排名
请求示例
GET /api/coin?page=1&page_size=20
GET /api/coin?all=1&page=1&page_size=20
GET /api/coin?top=1&page=1&page_size=9
返回示例(排行榜)
{
  "page": 1,
  "total": 454,
  "total_pages": 51,
  "rankings": [
    {"user_id":1,"username":"dianso","avatar_path":"/data/user/1/avatar.svg","coin_balance":27672,"rank":1},
    {"user_id":416,"username":"白夜染心","avatar_path":"/data/user/416/avatar_1748186248394.png","coin_balance":5772,"rank":2},
    {"user_id":202,"username":"呵呵","avatar_path":"","coin_balance":1704,"rank":4}
  ]
}
返回示例(金币记录)
{
  "page": 1,
  "total": 277,
  "total_pages": 14,
  "records": [
    {"id":2870,"user_id":1,"username":"dianso","amount":105,"type":"signin","description":"每日签到奖励","related_id":{"Int64":0,"Valid":false},"created_at":"2025-06-29T00:20:19+08:00"}
  ]
}
说明
  • 排行榜模式(top=1)和金币记录模式返回结构不同。
  • 排行榜头像如为空,前端可用 /api/avatar?size=28&seed=用户名 兜底。
  • 金币记录 amount 为正表示收入,为负表示支出。
  • type 字段详见前端 type->中文映射。

/api/badges

获取所有徽章及其发放数量。

请求方式GET /api/badges
请求参数
返回字段
字段类型说明
idint徽章ID
namestring徽章名称
colorstring徽章颜色(HEX)
text_colorstring徽章文字颜色(HEX)
descriptionstring徽章描述
logostring徽章图片URL
countint获得该徽章的作品数量
示例
GET /api/badges

返回:
[
  {
    "id": 1,
    "name": "精品作品",
    "color": "#FFD700",
    "text_color": "#000000",
    "description": "获得精品作品称号的小说",
    "logo": "/static/img/badges/gold.png",
    "count": 12
  },
  {
    "id": 2,
    "name": "月票冠军",
    "color": "#00BFFF",
    "text_color": "#ffffff",
    "description": "月票排行第一的作品",
    "logo": "/static/img/badges/champion.png",
    "count": 5
  }
]

/api/user

获取用户列表,支持分页、角色筛选、模糊搜索,返回总数和各角色数量。适用于前端用户列表、管理后台等场景。

请求方式GET /api/user
请求参数
参数类型必填说明
pageint页码,默认1
page_sizeint每页数量,默认20,最大100
roleint用户角色(1=用户,2=贡献者,0=管理员,9=小黑屋)
keywordstring用户名模糊搜索
返回字段
字段类型说明
usersarray用户简要信息数组
totalint总用户数(符合筛选条件)
pageint当前页码
page_sizeint每页数量
role_countsobject各角色用户数量,如{"":123, "1":100, "2":10, "0":5, "9":8}
用户对象结构
字段类型说明
idint用户ID
usernamestring用户名
roleint用户角色
avatarstring头像URL
created_atstring注册时间(YYYY-MM-DD)
返回示例
{
  "users": [
    {"id": 1, "username": "admin", "role": 0, "avatar": "/api/avatar?name=admin", "created_at": "2023-01-01"},
    {"id": 2, "username": "user1", "role": 1, "avatar": "/api/avatar?name=user1", "created_at": "2023-01-02"}
  ],
  "total": 123,
  "page": 1,
  "page_size": 20,
  "role_counts": {"": 123, "1": 100, "2": 10, "0": 5, "9": 8}
}
说明
  • role_counts 对象的 key 说明:""为全部,"1"为普通用户,"2"为贡献者,"0"为管理员,"9"为小黑屋用户。
  • avatar 字段如果为空,建议用 /api/avatar?name=用户名 生成默认头像。
  • 支持分页、角色筛选和模糊搜索,可用于前端用户列表、管理后台等多种场景。
用法补充
  • 分页获取用户列表: GET /api/user?page=1&page_size=20
  • 按角色和关键词搜索: GET /api/user?role=1&keyword=张三
  • 获取单用户详情: GET /api/user?id=123
返回示例(单用户):
{
  "id": 2,
  "username": "test",
  "role": 1,
  "avatar": "/avatar/2.png",
  "created_at": "2024-06-02"
}

/api/user/role

切换当前登录用户的身份(普通用户/贡献者)。需登录。

请求方式GET /api/user/role?role=1|2
请求参数
参数类型必填说明
roleint目标身份,1=普通用户,2=贡献者
返回
操作成功后会重定向回来源页面,无JSON返回。
说明
  • 仅普通用户和贡献者可互相切换。
  • 需登录。
  • 切换后自动重定向回来源页面。
示例
GET /api/user/role?role=2

# 切换为贡献者

GET /api/user/role?role=1

# 切换为普通用户

/api/signin

用户每日签到接口,支持获取签到信息和执行签到操作。

请求方式GET /api/signin POST /api/signin
GET 请求参数
参数类型必填说明
user_idint查询指定用户的签到信息(所有人可查)
POST 请求参数
无需参数,直接POST即可完成签到,需登录。
返回字段
字段类型说明
successbool操作是否成功
messagestring提示信息
statsobject签到统计信息(GET)
dailyobject每日签到统计(GET)
rankingsarray签到排行榜(GET)
total_usersint总用户数(GET)
has_signed_todaybool今日是否已签到(GET)
level_daysarray等级天数配置(GET)
announcementstring签到公告(GET)
today_signersarray今日已签到用户(GET)
rewardint签到获得的金币(POST)
total_daysint累计签到天数(POST)
levelint当前等级(POST)
示例
GET /api/signin

返回:
{
  "success": true,
  "stats": { "TotalSignins": 12, "Level": 2, ... },
  "daily": { "TodaySignins": 5, ... },
  "rankings": [ ... ],
  "total_users": 123,
  "has_signed_today": true,
  "level_days": [0,10,30,...],
  "announcement": "每日签到送金币!",
  "today_signers": [ { "user_id": 1, "username": "张三" } ]
}

POST /api/signin

返回:
{
  "success": true,
  "message": "签到成功,获得金币!",
  "reward": 8,
  "total_days": 12,
  "level": 2
}

/api/avatar

生成动物风格头像,支持多种参数和动物类型。

请求方式GET /api/avatar
请求参数
参数类型必填说明
sizeint头像尺寸,默认200,范围50-500
seedint/string随机种子,相同种子生成相同头像
stylestring头像风格,animal=动物头像(默认)
animalstring指定动物类型,支持:
cat 猫、dog 狗、rabbit 兔子、bear 熊、fox 狐狸、tiger 老虎、lion 狮子、monkey 猴子、pig 猪、panda 熊猫、frog 青蛙、chick 小鸡、duck 鸭子、cow 奶牛、sheep 羊、squirrel 松鼠、koala 考拉、hippo 河马、giraffe 长颈鹿、penguin 企鹅、horse 马、deer 鹿、elephant 大象、wolf 狼、mouse 老鼠、owl 猫头鹰、camel 骆驼、crocodile 鳄鱼、zebra 斑马、goat 山羊、hedgehog 刺猬、raccoon 浣熊、whale 鲸鱼、dolphin 海豚、shark 鲨鱼、eagle 鹰、parrot 鹦鹉、turtle 乌龟、snake 蛇、bat 蝙蝠
效果演示
熊头像

bear
奶牛头像
奶牛
cow
长颈鹿头像
长颈鹿
giraffe
考拉头像
考拉
koala
熊猫头像
熊猫
panda
老鼠头像
老鼠
mouse
兔子头像
兔子
rabbit
蛇头像

snake
示例请求
GET /api/avatar?size=200&seed=1&style=animal&animal=bear

/api/hot

获取热门榜单,包括热门标签、热门作家、热门作品、热门搜索。

请求方式GET /api/hot
请求参数
参数类型必填说明
typestring榜单类型,可选 tags(热门标签,默认)、author(热门作家)、novel(热门作品)、search(热门搜索)
limitint返回条数,默认10,最大100
返回字段
字段类型说明
namestring标签/作家/作品/搜索词名称
authorstring(仅热门作品)作者笔名
countint热度(如浏览量、搜索次数等)
示例
GET /api/hot?type=novel&limit=3

返回:
[
  {"name": "苟在初圣魔门当人材", "author": "鹤守月满池", "count": 233},
  {"name": "人在无限,开始速通", "author": "小抽大象", "count": 160},
  {"name": "神祇风暴", "author": "骷髅精灵", "count": 106}
]
此处可补充管理类API,如金币发放、后台统计等。