Developer Guide

Novel API Platform 开发者接入指南

面向接入方网站和开发者的全收费小说数据 API，提供书籍、分类、章节目录和章节正文等标准化接口。测试 API 仅用于查看返回格式，不开放完整书库。

API Base URL: https://dpyl.org/api/v1 API Version: v1 Headers: X-Client-Key + X-Plan-Key Response: data / meta
测试 API 正式接口调试 查看示例代码

平台说明

面向接入方网站和开发者的全收费小说数据 API，提供书籍、分类、章节目录和章节正文等标准化接口。测试 API 仅用于查看返回格式，不开放完整书库。

API Base URL

https://dpyl.org/api/v1

API 版本

v1

联系邮箱

support@example.com

套餐说明

平台只提供 3个月、8个月、12个月三类正式收费套餐。套餐包含期限、本月额度、每分钟限流和价格说明；具体价格、额度和升级由平台管理员配置。

调用限制说明

平台会按接入方套餐、订阅状态、积分余额、月度额度、每分钟限流和访问策略校验正式 API。积分低于 200 返回 INSUFFICIENT_BALANCE，超额度返回 MONTHLY_QUOTA_EXCEEDED，超限流返回 RATE_LIMIT_EXCEEDED。

缓存说明

接口响应可能包含 cache、source、fallback 等 meta 信息，接入方应结合业务需要做本地缓存和重试控制。

如何携带接入方 Key 和套餐 API

正式 API 必须同时使用接入方 Key 和套餐 API。每次请求通过 X-Client-Key 与 X-Plan-Key Header 传递，不要将密钥暴露在前端代码中。

GET https://dpyl.org/api/v1/books
	X-Client-Key: YOUR_CLIENT_KEY
	X-Plan-Key: YOUR_PLAN_KEY

联系方式说明

如需开通接入、调整额度或反馈接口问题，请提供接入方名称、业务场景、预计调用量和技术联系人信息。已开通的接入方可登录 /portal 查看套餐、余额/积分、API 接入和调用监控。

测试 API

测试 API 只用于查看返回格式，不要求正式双 Key，不计入正式调用日志，也不提供完整书库。正式调用仍必须完成邀请码注册、套餐、余额和双 Key 校验。

GET /api/test/books

常用接口列表

以下固定接口由系统自动列出；真实接口路径、参数和响应字段以 OpenAPI Schema 为准。

方法 路径 用途
GET /api/v1/books?q=关键词 搜索或获取书籍列表
GET /api/v1/categories 获取分类列表
GET /api/v1/categories/{category_id}/books 获取分类下书籍
GET /api/v1/books/{book_id} 获取书籍详情
POST /api/v1/books/{book_id}/ratings 提交站内用户书籍评分
GET /api/v1/books/{book_id}/ratings/summary 获取书籍评分统计
GET /api/v1/books/{book_id}/chapters 获取章节目录
GET /api/v1/chapters/{chapter_id} 获取章节内容

补充说明

接口真实路径和参数以 OpenAPI Schema 为准；后台补充说明只用于解释接入策略，不改变真实路由。

统一返回格式 data/meta

data 承载接口数据，meta 承载缓存、来源、fallback 和分页等附加信息。

{
  "data": [],
  "meta": {
    "cache": "hit|miss|stale|none",
    "source": "local|source_code|null",
    "fallback": false,
    "total": 0,
    "page": 1,
    "page_size": 20,
    "total_pages": 10,
    "total_chars": 12000
  }
}

GET /api/v1/chapters/{chapter_id} 默认返回完整正文；需要章节内分页时传 page 和 page_size，例如 ?page=1&page_size=1200。

错误响应格式 detail.code / detail.message

接口失败时统一返回 detail.code 和 detail.message，接入方应优先根据 code 做程序化处理。

{
  "detail": {
    "code": "ERROR_CODE",
    "message": "Human readable message."
  }
}

错误码说明

常见固定错误码如下，补充说明由后台配置，完整错误信息以实际响应为准。

错误码 HTTP 状态 说明
API_KEY_MISSING 401 请求未同时携带 X-Client-Key 和 X-Plan-Key。
API_KEY_INVALID 403 接入方 Key 或套餐 API 不存在，或不满足访问策略。
API_KEY_DISABLED 403 接入方 Key 或套餐 API 已被管理员禁用。
API_KEY_REVOKED 403 接入方 Key 或套餐 API 已撤销。
CLIENT_PENDING 403 接入方账号尚未启用，不能调用正式收费 API。
CLIENT_SUSPENDED 403 接入方状态不可用。
CLIENT_DISABLED 403 接入方已禁用。
SUBSCRIPTION_REQUIRED 403 接入方尚未开通有效套餐订阅。
SUBSCRIPTION_EXPIRED 403 接入方订阅未生效或已过期，请联系管理员续费。
PLAN_DISABLED 403 订阅套餐已停用。
INSUFFICIENT_BALANCE 403 接入方余额/积分低于平台门槛。
MONTHLY_QUOTA_EXCEEDED 429 当前周期调用额度已用完。
RATE_LIMIT_EXCEEDED 429 请求频率超过套餐限制。
ORIGIN_NOT_ALLOWED 403 请求来源不在接入方允许域名内。
IP_NOT_ALLOWED 403 请求 IP 不在接入方允许列表内。
RATING_ALREADY_EXISTS 409 同一接入方站点内，该站内用户已经评价过这本书。
TEST_API_DISABLED 403 测试 API 当前未启用。
SOURCE_UNAVAILABLE 503 上游或内容来源暂不可用。
REQUEST_TOO_LARGE 413 请求体或上传文件超过平台限制。
BAD_REQUEST 400 请求参数格式不正确或业务参数无效。
NOT_FOUND 404 请求的资源不存在。
VALIDATION_ERROR 422 请求参数未通过接口校验。
INTERNAL_ERROR 500 服务端处理失败。
API_ERROR 4xx/5xx 未归类的 API 错误。

补充说明

如遇持续性鉴权、额度或内容来源错误，请带上请求时间、接口路径和错误码联系平台排查。

示例代码

以下示例展示如何携带 X-Client-Key 和 X-Plan-Key 获取书籍列表。

JavaScript fetch

const clientKey = "YOUR_CLIENT_KEY";
const planKey = "YOUR_PLAN_KEY";

const response = await fetch("https://dpyl.org/api/v1/books", {
  headers: {
    "X-Client-Key": clientKey,
    "X-Plan-Key": planKey
  }
});

const payload = await response.json();

Python requests

import requests

client_key = "YOUR_CLIENT_KEY"
plan_key = "YOUR_PLAN_KEY"
response = requests.get(
    "https://dpyl.org/api/v1/books",
    headers={
        "X-Client-Key": client_key,
        "X-Plan-Key": plan_key,
    },
)

payload = response.json()

PHP cURL

$clientKey = "YOUR_CLIENT_KEY";
$planKey = "YOUR_PLAN_KEY";
$ch = curl_init("https://dpyl.org/api/v1/books");

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-Client-Key: " . $clientKey,
    "X-Plan-Key: " . $planKey,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$payload = json_decode(curl_exec($ch), true);
curl_close($ch);

Node.js axios

import axios from "axios";

const clientKey = "YOUR_CLIENT_KEY";
const planKey = "YOUR_PLAN_KEY";
const response = await axios.get("https://dpyl.org/api/v1/books", {
  headers: {
    "X-Client-Key": clientKey,
    "X-Plan-Key": planKey
  }
});

const payload = response.data;

在线接口测试

此区域内嵌 Swagger UI，使用当前服务的 OpenAPI schema。点击 Authorize 填入 X-Client-Key 和 X-Plan-Key 后，即可展开接口并使用 Try it out 发起测试请求。

Schema 来源：/openapi.json 鉴权方式：X-Client-Key + X-Plan-Key
在线接口测试初始化失败，请刷新页面后重试。

接入流程说明

1. 向平台获取邀请码。 2. 使用邀请码注册接入方账号，填写网站、联系人和邮箱信息；注册成功后账号会直接启用。 3. 开通 3个月、8个月或12个月正式套餐，并确认余额/积分不少于 200。 4. 注册后获得固定接入方 Key；每次购买套餐会获得一个独立套餐 API。 5. 在接入方服务端保存接入方 Key 和套餐 API，通过 X-Client-Key + X-Plan-Key Header 调用 /api/v1/*。 6. 上线后通过 /portal 监控套餐、余额、调用趋势、错误码和额度使用情况。