API 规则开发
API 规则不解析网页 HTML,而是直接请求网站提供的 JSON 接口。相比 XPath 规则,它通常不受页面布局变化影响,也更容易准确地获取作品、线路和剧集信息。
本教程以 TvTFun 为例,完成一条 API 搜索、API 选集、播放页构造的规则,并补充说明详情页地址模板、分隔字符串选集等常见场景。第三方站点可能随时调整接口,教程中的字段以编写本文时的实际响应为准。
NOTE
API 规则基础能力自 Kazumi API level 8 起提供;API 搜索的详情页地址模板(sourceTemplate)需要 Kazumi API level 9(v2.3.9)或更高版本。请使用新版客户端并在规则编辑器中选择“API”搜索或选集类型。
API 规则的数据流
一条完整的 API 规则会依次完成以下操作:
@keyword
→ 搜索接口返回作品列表
→ 提取作品名称(namePath)与条目来源(sourcePath)
→ (可选)若配置了详情页地址模板(sourceTemplate),将 @source 替换为条目来源以生成完整地址
→ 将所得来源作为 @source 传给选集请求(API 选集接口或 XPath 详情页)
→ 提取播放线路、剧集信息与响应变量
→ 直接读取剧集地址,或使用响应变量与线路/剧集序号构造播放页地址Kazumi 目前支持 GET 和 POST 请求。每个请求都可以分别配置 URL、请求头、查询参数和请求体:
- 请求头和查询参数填写 JSON 对象。
POST请求体可选择“JSON”或“表单”;GET请求通常选择“无”。- 搜索请求可使用
@keyword,Kazumi 会替换为用户输入的关键词。 - 搜索结果可选配置详情页地址模板(
sourceTemplate),其中的@source会被替换为经过 URL 编码的条目来源值。 - 选集请求可使用
@source,Kazumi 会替换为搜索阶段最终生成的来源值(配置了详情页地址模板时为展开后的完整地址,未配置时为原始条目来源)。 - 播放页还可使用响应变量,以及从 0 开始的
@roadIndex、@episodeIndex和从 1 开始的@roadNumber、@episodeNumber。
准备工作
在 Kazumi 中依次进入 我的 → 规则管理 → 添加规则 → 新建规则,在“基本”、“搜索”和“选集”分段中填写以下基础信息:
| 字段 | 值 |
|---|---|
| 规则名称 | TvTFun |
| 规则版本 | 1.0 |
| 基础地址 | https://www.tvtfun.net/ |
| 搜索规则类型 | API |
| 选集规则类型 | API |
接口分析通常通过浏览器开发者工具的“网络”面板完成。打开面板后选择 Fetch/XHR,执行一次搜索,再查看新增请求的 URL、查询参数和响应 JSON。
TvTFun 无法打开开发者工具时
TvTFun 会拦截页面中的 F12、Ctrl+Shift+I、右键菜单,并可能在检测到停靠式开发者工具后跳转。可以先在空白标签页中通过浏览器菜单打开开发者工具,将其切换为独立窗口,再访问 TvTFun。
如果仍然发生跳转,可以直接在终端复现本教程需要的请求。开发者工具只用于发现接口,不是 Kazumi 运行规则的必要条件。
curl --get "https://www.tvtfun.net/api/videos/search" --data-urlencode "q=紫罗兰永恒花园" --data "pageSize=20"从搜索响应复制第一项的 id 后,可以继续查看详情响应:
curl "https://www.tvtfun.net/api/videos/cmp2xb96k27h2i9m8eucbwit2"该站点的这两个接口无需登录、Cookie 或特殊请求头。
Kazumi 支持的 JSONPath
JSONPath 的作用类似于 JSON 数据中的“地址”。Kazumi 使用一个受限子集,以 $ 表示当前数据的根节点。
| 写法 | 含义 | 是否支持 |
|---|---|---|
$.data.videos |
依次读取对象字段 | 支持 |
$.data.videos[*] |
读取数组中的所有元素 | 支持 |
$.data.videos[0] |
读取指定数组元素 | 支持 |
$['play-sources'] |
读取需要引号表示的字段名 | 支持 |
$..videos |
递归查找 | 不支持 |
$.videos[?(@.enabled)] |
条件过滤 | 不支持 |
$.videos[0:2] |
数组切片 | 不支持 |
$.videos.length() |
函数或表达式 | 不支持 |
“相对条目”“相对线路”和“相对剧集”表示 $ 会分别指向当前作品、当前线路或当前剧集,而不是整个接口响应。不要在这些字段中重复外层路径。
配置搜索接口
在 TvTFun 的搜索框中输入“紫罗兰永恒花园”时,可以在网络面板中发现相同搜索接口。网页自身使用 pageSize=5,规则可以将它调整为 20,以便一次返回更多结果:
GET https://www.tvtfun.net/api/videos/search?q=紫罗兰永恒花园&pageSize=20响应结构精简后如下:
{
"data": {
"videos": [
{
"id": "cmp2xb96k27h2i9m8eucbwit2",
"name": "紫罗兰永恒花园",
"slug": "183878"
}
],
"total": 2
}
}在“搜索”分段的 API 配置下填写:
| 字段 | 值 |
|---|---|
| 搜索请求方法 | GET |
| 搜索请求地址 | https://www.tvtfun.net/api/videos/search |
| 搜索请求头 | 留空 |
| 搜索查询参数 | {"q":"@keyword","pageSize":20} |
| 搜索请求体类型 | 无 |
| 搜索结果列表路径 | $.data.videos[*] |
| 条目名称路径 | $.name |
| 条目来源路径 | $.id |
| 详情页地址模板 | 留空 |
$.data.videos[*] 先得到每一个作品对象。随后 Kazumi 以每个作品为新的根节点,通过 $.name 读取显示名称,通过 $.id 读取下一步需要的内部 ID。由于本例的选集请求同样是 API 接口,并直接在 URL 中接收该内部 ID,因此“详情页地址模板”保持留空即可。
WARNING
不要在“条目来源路径”中使用 $.slug。TvTFun 的详情接口接收内部 id,而 slug 只用于最后构造网页播放地址。
使用详情页地址模板拼接裸 ID(sourceTemplate)
部分网站的搜索接口只返回纯数字或短字符串形式的裸 ID(如 12345),而不返回完整路径或 URL。当你需要将搜索结果交给 XPath 选集规则请求详情网页,或希望搜索结果直接产出完整详情页地址时,可以填写详情页地址模板(URL,可选)(JSON 字段为 sourceTemplate)。
- 校验要求:非空时必须包含
@source,否则编辑器会拒绝保存。 - 替换方式:Kazumi 会将条目来源值进行
Uri.encodeComponent编码后,直接替换模板中的@source。因为采用直接字符串替换,@source可以紧跟在字母或数字之后(无需使用分隔符隔开)。
例如,某站点搜索接口返回:
{
"data": [
{ "id": 10492, "title": "紫罗兰永恒花园" }
]
}若该站点的作品详情页地址形如 https://example.com/GV10492 或 https://example.com/bangumi/10492.html,则可配置:
| 字段 | 值 |
|---|---|
| 条目来源路径 | $.id |
| 详情页地址模板 | https://example.com/GV@source(或 https://example.com/bangumi/@source.html) |
解析后,搜索条目的来源地址会变为 https://example.com/GV10492,随后可直接由 XPath 选集规则请求并解析 HTML,也可在规则测试面板中直接看到完整链接。
配置选集接口
将搜索结果中的内部 ID 放入详情接口,可以得到作品信息、播放线路和剧集:
GET https://www.tvtfun.net/api/videos/cmp2xb96k27h2i9m8eucbwit2响应结构精简后如下:
{
"data": {
"id": "cmp2xb96k27h2i9m8eucbwit2",
"slug": "183878",
"playSources": [
{
"name": "线路B",
"episodes": [
{ "name": "第1集", "url": "protected", "sort": 0 },
{ "name": "第2集", "url": "protected", "sort": 1 }
]
},
{
"name": "线路C",
"episodes": [
{ "name": "第01集", "url": "protected", "sort": 0 }
]
}
]
}
}在“选集”分段的 API 配置下填写:
| 字段 | 值 |
|---|---|
| 选集请求方法 | GET |
| 选集请求地址 | https://www.tvtfun.net/api/videos/@source |
| 选集请求头 | 留空 |
| 选集查询参数 | 留空 |
| 选集请求体类型 | 无 |
| 选集响应格式 | 嵌套 JSON |
| 播放线路列表路径 | $.data.playSources[*] |
| 线路名称路径 | $.name |
| 剧集列表路径 | $.episodes[*] |
| 剧集名称路径 | $.name |
| 播放入口地址路径 | 留空 |
| 响应变量 | {"slug":"$.data.slug"} |
| 播放页地址模板 | https://www.tvtfun.net/video/@slug/play |
| 播放页查询参数 | {"source":"@roadIndex","episode":"@episodeIndex"} |
为什么播放入口地址路径必须留空
详情响应中的 url 固定为 protected,它不是可以访问的媒体地址或网页地址。如果把播放入口地址路径填写为 $.url,Kazumi 最终只会尝试访问类似 https://www.tvtfun.net/protected 的无效地址。
TvTFun 真正的播放入口由作品 slug、线路序号和剧集序号组成。例如第二集会被构造为:
https://www.tvtfun.net/video/183878/play?source=0&episode=1因此需要先通过响应变量保存 $.data.slug,再在播放页模板中使用 @slug。source 和 episode 都从 0 开始,恰好对应 @roadIndex 和 @episodeIndex。
补充:分隔字符串响应格式(delimited)
除 嵌套 JSON 外,许多采用苹果 CMS(MacCMS)等架构的站点接口会将线路名和剧集列表拼接在单个字符串中返回,例如:
{
"list": [
{
"vod_play_from": "线路A$$$线路B",
"vod_play_url": "第01集$https://example.com/play/1-1#第02集$https://example.com/play/1-2$$$正片$https://example.com/play/2-1"
}
]
}此时可将选集响应格式切换为 分隔字符串,并配置:
| 字段 | 默认值 / 示例 | 说明 |
|---|---|---|
| 线路名称串路径 | $.list[0].vod_play_from |
提取包含所有线路名称的字符串 |
| 线路剧集串路径 | $.list[0].vod_play_url |
提取包含所有线路与剧集的字符串 |
| 线路分隔符 | $$$ |
拆分不同播放线路 |
| 剧集分隔符 | # |
在同一线路内拆分不同剧集 |
| 名称与地址分隔符 | $ |
在单个剧集条目内拆分剧集名称与地址 |
分隔出的剧集地址同样可以作为 @episodeUrl 配合“播放页地址模板”进一步构造最终播放页。
测试规则
保存前点击规则编辑器底部的 测试规则 按钮,并按以下顺序检查:
- 搜索“紫罗兰永恒花园”,在“搜索请求”和“结果解析”中确认返回了同名作品及预期的来源值。
- 在“播放线路”中确认第一条搜索结果能解析出“线路B”“线路C”等播放线路及对应集数。
- 检查第一条线路的第二集,最终地址应为
https://www.tvtfun.net/video/183878/play?source=0&episode=1。 - 保存后选择剧集,确认 Kazumi 能进入播放页进行视频资源嗅探。
接口解析成功只表示规则配置正确。第三方站点的视频源仍可能因为资源失效、地区限制或临时防护而无法播放。
完整规则
下面是本教程对应的完整 JSON。在规则编辑器中保存包含 API 模式的规则时,api 字段会自动标记为当前客户端的 API 级别(9),旧 XPath 字段在 API 模式下保留为空字符串。
{
"api": "9",
"type": "anime",
"name": "TvTFun",
"version": "1.0",
"muliSources": true,
"useWebview": true,
"useNativePlayer": true,
"usePost": false,
"useLegacyParser": false,
"adBlocker": false,
"userAgent": "",
"baseURL": "https://www.tvtfun.net/",
"searchURL": "",
"searchList": "",
"searchName": "",
"searchResult": "",
"chapterRoads": "",
"chapterResult": "",
"referer": "",
"searchMode": "api",
"chapterMode": "api",
"searchApiConfig": {
"request": {
"method": "GET",
"url": "https://www.tvtfun.net/api/videos/search",
"query": {
"q": "@keyword",
"pageSize": 20
}
},
"listPath": "$.data.videos[*]",
"namePath": "$.name",
"sourcePath": "$.id"
},
"chapterApiConfig": {
"request": {
"method": "GET",
"url": "https://www.tvtfun.net/api/videos/@source"
},
"format": "nested",
"roadsPath": "$.data.playSources[*]",
"roadNamePath": "$.name",
"episodesPath": "$.episodes[*]",
"episodeNamePath": "$.name",
"episodeUrlPath": "",
"variables": {
"slug": "$.data.slug"
},
"episodePage": {
"url": "https://www.tvtfun.net/video/@slug/play",
"query": {
"source": "@roadIndex",
"episode": "@episodeIndex"
}
}
},
"antiCrawlerConfig": {
"enabled": false,
"captchaType": 1,
"captchaImage": "",
"captchaInput": "",
"captchaButton": "",
"captchaDetectType": 1,
"captchaDetectValue": "",
"captchaScript": ""
}
}常见错误
搜索接口有数据,但 Kazumi 没有结果
确认列表路径包含数组通配符 [*],即 $.data.videos[*]。名称和来源路径应相对于单个作品填写为 $.name、$.id,不要重复 $.data.videos[*]。
提示 JSONPath 不受支持
移除递归查找、过滤器、切片或函数调用,只使用字段、数组下标、通配符和带引号字段名。所有 JSONPath 都必须以 $ 开头。
提示“详情页地址模板必须引用 @source”
如果填写了搜索的“详情页地址模板”(sourceTemplate),模板中必须包含 @source 占位符(例如 https://example.com/GV@source)。如果不需要将条目来源拼接为完整地址,请将该字段留空。
选集请求返回“视频不存在”或地址重复拼接
- 对于 TvTFun,确认条目来源路径使用的是
$.id而不是$.slug,且搜索的“详情页地址模板”保持留空,使选集 URL 中的@source被替换为形如cmp2xb96k27h2i9m8eucbwit2的内部 ID。 - 如果已在搜索阶段通过“详情页地址模板”生成了完整 URL,注意
@source已经是完整地址,切勿在选集请求地址中再次重复拼接域名前缀。
剧集地址变成了 /protected
清空播放入口地址路径,并检查响应变量、播放页地址模板和播放页查询参数是否完整填写。protected 只是接口隐藏真实资源时使用的占位文本。
线路或剧集错位
TvTFun 的 source 和 episode 参数从 0 开始,应使用 @roadIndex 和 @episodeIndex。@roadNumber 和 @episodeNumber 从 1 开始,不适用于本例。
JSON 配置无法保存
请求头、查询参数、响应变量和播放页查询参数都必须是合法 JSON 对象。键名和字符串使用双引号,末尾不要添加多余逗号。