API 接口 · 开放平台开发文档

00概览

这里收录本站已经对外开放、可以稳定调用的接口。所有接口都无状态：每次请求带全量参数，服务端算完即返回，不保存会话、不需要登录。

接口模块加载中…

i

三个模块，用途完全不同： 五子棋引擎是本地算路程序（免费、毫秒级、棋力稳定）；中考查询与短视频解析是代理型接口，把上游服务的结果整理成 JSON。站点内部的 AI 对话 / 联网搜索使用服务端 DeepSeek Key，按量计费，不对外文档化。

0130 秒上手（以五子棋为例）

三步：拼一个 15×15 棋盘 → POST 到 /api/v1/gomoku/move → 读出 row/col。

bash · 最小可用请求

!

棋盘必须严格 15×15。 行数、列数不对会直接返回 400；坐标是 (row, col)，取值 0–14， (0,0) 在左上角；0=空、1=黑、2=白。

02接口总览

模块	方法	地址	认证	计费
五子棋 · 落子	POST	/api/v1/gomoku/move	无	免费
五子棋 · 分析	POST	/api/v1/gomoku/analyze	无	免费
五子棋 · 模型目录	GET	/api/v1/gomoku/models	无	免费
五子棋 · 健康检查	GET	/api/v1/gomoku/health	无	免费
五子棋 · 大模型落子	POST	/api/v1/gomoku/llm-move	无	服务端承担
五子棋 · 棋评	POST	/api/v1/gomoku/comment	无	服务端承担
中考成绩查询	GET / POST	/api/v1/zkscore/search	无	免费
短视频去水印解析	GET / POST	qsy.cwj666.top/parse	无	免费

除特别说明外，域名均为 https://api.www.cwj666.top。

✓

外部接入请统一走 /api/v1。 它是给第三方用的版本化入口：允许任意 Origin（Access-Control-Allow-Origin: *），第三方网页可以直接 fetch，独立限流 600 次/分钟/IP。站内旧路径 /api/gomoku/* 仍然可用，但只对本站域名放行。 GET /api/v1 会返回版本、跨域策略、限流与完整接口清单，可用来探活或自动生成客户端。

03五子棋引擎

纯本地算路程序（VCF 连续冲四必胜、迭代加深 Alpha-Beta、精确棋型/威胁识别），随 Node 服务一起部署。每次请求把完整棋盘传上来，服务端算一手返回，不保存对局。

接口明细

所有接口统一返回 { code, message?, data }；HTTP 状态码与 code 一致。

POST /api/v1/gomoku/move 让指定引擎模型算一手

请求参数

字段	类型	必填	说明
board	number[15][15]	是	棋盘二维数组，0 空 / 1 黑 / 2 白
player	1 \| 2	否	轮到谁走，默认 `2`（白）
level	string	否	easy / medium / hard / master / god，默认 hard
model	string	否	引擎模型 id 或别名，默认 feiyang-v6
withCommentary	boolean	否	true 时额外调用一次 DeepSeek 生成棋评（慢、有费用）
llmModel	string	否	棋评用的云端模型，仅 withCommentary 生效

请求示例

json · 请求体（跟随下方调试台实时变化）

展开完整请求体（15 × 15 共 225 个数字）

响应字段

字段	类型	说明
row / col	number	引擎选出的落点，0–14
reason	string	中文决策理由
tactic	string	决策层级：five / block-five / kill / vcf / search …
depth / nodes	number	搜索深度与展开节点数（部分层级为 0）
value	number	引擎内部评分，仅同一局内横向比较有意义
engineMs / serverMs	number	纯算路耗时 / 服务端总耗时
level / levelName	string	实际生效的档位
candidates	object[]	候选着法：{ row, col, value, attack, defend, text, selected }
engine / engineName	string	实际使用的模型（传别名时返回正式 id）
corrected	boolean	保留字段；本地引擎决策恒为 false

响应示例

json · 200 OK

POST /api/v1/gomoku/analyze 只分析不落子：候选点、双方连五点、局面复杂度

参数：board（必填）、player、model。用于做"这局该下哪"的分析面板或教学。

json · 响应示例（截断）

GET /api/v1/gomoku/models 模型目录 + 档位 + 当前默认模型

返回 engine（当前激活模型）、models[]（含 aliases/stage/code）、levels[]、llm[]。适合在客户端动态渲染下拉框。

json

GET /api/v1/gomoku/health 健康检查：引擎是否加载、模型清单

返回 engineLoaded、engineModelId、engineModels[]。适合做存活探针。

POST /api/v1/gomoku/llm-move 让 DeepSeek 选点（服务端承担费用，棋力弱于引擎）

参数：board、player、level（仅影响注入的情报深度）、 model（云端模型，目前仅 feiyang-v4-flash）、thinking（默认 false）。返回额外包含 decidedBy（llm / engine-safety / engine-fallback）、finishReason、usage、cost。

!

想赢棋请用 /move。 大模型只在"能读懂的棋局描述"上做一次性选择，没有搜索能力；实测在 15×15 中盘会漏掉必杀、也算不出 VCF。它的价值是"说人话"，不是"下棋"。

POST /api/v1/gomoku/comment 给某一手棋生成中文棋评

参数：board、player、move{row,col}、 model、thinking（默认 false，开启后会空转到截断且正文为空）。返回 comment（纯中文，100–250 字）、finishReason、usage、cost。

代码示例

示例里的棋盘与参数会跟随下方调试台实时变化，可以直接复制运行。

bash

javascript

node.js（18+，内置 fetch）

python（requests）

php（curl）

在线调试

点棋盘落子（可切换黑白），选好模型与档位，直接打线上接口。返回的落点会用蓝色准星标在棋盘上。

棋盘

引擎模型

算力档位

轮到谁走

落子数：0

等待请求…

点「示例局面」或直接在棋盘上落子，然后点「请求落子」。

04中考成绩查询

把河源市中考成绩查询原站的结果整理成 JSON，免验证码、免登录，方便小程序 / App / 脚本集成。数据来源为上游原站，本接口只做中转与字段整理。

i

正在检测上游查询系统状态…

!

为什么有时连不上： 上游站点只开放 8088 端口，并且会按来源 IP 做屏蔽。本站服务器的出口 IP 目前被上游丢弃（连接超时），接口返回 502；恢复调用需要换一个出口 IP 或加一层中转。接口本身、历年场次号与文档都已就绪，换出口后无需改代码。

POST https://api.www.cwj666.top/api/v1/zkscore/search GET 同地址，参数走 query

参数	类型	必填	说明
templateId	string	是	考试场次 ID，每年会变，以原站首页下拉框为准；历年值见下方对照表
userName	string	是	考生姓名
identity	string	是	考生号或身份证号

bash

json · 响应

上游只在放榜期间开放；关闭期间本接口返回 503 与 upstream: "paused"，不会把上游的 HTML 错误页塞给你。

GET /api/v1/zkscore/status 先探活：上游是否开放 + 历年场次号

建议客户端启动时先调这个接口：upstream 为 open 再让用户填表，避免白跑一次。

json · 响应

历年考试场次号（templateId）

这个号每年由原站重新生成，旧号在下一届查不到成绩。把每年用过的号记在这里，明年（2027）直接翻出来对照，不用再去原站首页扒下拉框。

年份	场次	templateId	状态
2026	九年级	100017842554324123	已归档
2026	八年级	100017842555943567	已归档
2027	九年级 / 八年级	待原站公布	待补充

!

2027 年怎么更新： 放榜前打开原站 http://zkcj.heyuanedu.cn:8088，在页面下拉框里读出新的 option value，加到服务端 server/routes/zkscore-api.js 的 TEMPLATE_HISTORY[2027] 即可，历史年份不需要删。

!

涉及考生隐私： 请只在获得本人授权的前提下调用，不要批量遍历考生号，不要把结果落库或二次分发。接口本身不记录查询内容，但请自行遵守《个人信息保护法》相关要求。

05短视频去水印解析

传入作品分享链接，返回无水印直链、标题、封面、作者等结构化信息。支持抖音、快手、小红书、微博、B 站、网易云音乐、汽水音乐、皮皮虾、YouTube、TikTok、西瓜、微视等平台。

GET https://qsy.cwj666.top/parse?url=分享链接另有 Swagger 在线调试：/docs

bash

json · 响应（截断）

字段说明：data.video_url 无水印直链、title 标题、 cover 封面、author 作者、platform 平台标识。完整字段与平台列表见 qsy.cwj666.top/docs。

06通用规范

响应包络

json

{
  "code": 200,
  "message": "success",
  "data": { }
}

HTTP 状态码与 code 保持一致；失败时 message 是可读的中文原因。

错误码

HTTP	场景	处理建议
400	棋盘不是 15×15 / 行数据不合法 / 未知模型 / 参数缺失	检查 `board.length` 与每行长度；模型 id 见上文目录
404	中考查询未找到该考生	核对考试场次、姓名与考生号
429	超过限流（`/api/v1` 为 600 次/分钟/IP）	退避重试；批量评测请降低并发
500	服务内部异常（上游不可用也算这类）	带 `message` 上报；稍后重试
503	引擎未加载 / 未配置大模型 Key / 中考上游处于非考试季	检查 `/api/v1/gomoku/health`；中考用 `/api/v1/zkscore/status` 探活

跨域与版本

跨域：/api/v1/* 返回 Access-Control-Allow-Origin: *，任意域名都可以在浏览器里直接 fetch；不带 Cookie 凭证，因此不需要 credentials: 'include'。
预检缓存：Access-Control-Max-Age: 86400，同一页面 24 小时内每个接口只多一次 OPTIONS。
版本：/api/v1 只做向后兼容的增量变更；将来若有破坏性改动会另开 /api/v2，v1 至少保留 6 个月。
站内旧路径：/api/gomoku/* 仍可用，但只允许 https://www.cwj666.top 与本地调试来源，本站页面走这条。
公开接口无鉴权，请勿把它们当作需要保密的私有服务；也不要用于高频压测。

限流

开放平台 /api/v1/*：600 次/分钟/IP，超出返回 429，请退避重试。
站内接口 /api/*：200 次/分钟/IP，两者额度互不占用。
大模型接口（llm-move / comment）另按积分额度计量：额度用完返回 402，不影响本地引擎接口。

07注意事项

五子棋 · 坐标系与棋盘

棋盘固定 15×15，数组下标即坐标：board[row][col]，(0,0) 左上角。
服务端不检查轮次：请自行保证 player 与当前局面的手数一致（黑先）。
服务端也不判断胜负：连五、禁手、和棋都由你的客户端判断。
空棋盘也可以请求，引擎会走天元（7,7）。

五子棋 · 模型切换

model 是单次请求级的：切换 → 算路 → 还原，全程同步，不会影响其它并发请求。
传别名（如 feiyang-v4-pro）时，响应里的 engine 会给出实际生效的正式 id。
传了不存在的模型会返回 400 并列出可选 id，不会静默降级。
不同模型对同一局面可能给出不同落点，这是预期行为；做 A/B 时请固定 level。

性能与并发

算路是 CPU 密集的同步计算，单实例串行处理。不要用 god 档跑高并发压测。
hard 单步约 0.5–0.9 秒，god 约 3–4 秒；请把客户端超时设到 10 秒以上。
响应里的 engineMs 是纯算路时间，serverMs 含棋盘解析与候选统计，排障时看后者。

代理型接口（中考 / 短视频）

结果依赖上游服务，字段可能随上游调整；请做好缺字段兜底。
中考查询涉及个人信息，只在获得授权时调用，不要批量抓取。
短视频解析仅供个人学习与备份使用，请遵守各平台版权与使用条款。

08常见问题

为什么同一个局面，两次请求结果不一样？

引擎在"等价着法"之间会做随机选择（避免每局完全一样）。做确定性测试时请固定第一手，或改用 /analyze 看候选排序。

能直接用接口下一整局吗？

可以，但服务端不保存棋局：每手都要把当前完整棋盘 POST 上来。流程是「我落子 → 更新本地 board → 请求 /move → 把返回的 row/col 写回 board」。

`value` 是胜率吗？

不是。它是引擎内部评分，只在同一局面的候选之间横向比较有意义；出现负数说明当前评估对我方不利。

为什么 `/llm-move` 下的棋比 `/move` 差？

大模型没有搜索能力，只能凭盘面描述做一次性判断，复杂局面会漏杀漏防。它适合"陪聊式对局"，正经对局请用本地引擎。

AI 助手 / 联网搜索的接口在哪？

那两个接口使用服务端 DeepSeek Key 按量计费，只供本站页面使用，暂不对外开放，因此不在本文档中给出调用方式。

09相关页面

模型研发中心档案

models.html

Feiyang 3.0 ~ 6.0 的架构、核心改动、横向评测成绩与迭代路线。

五子棋对战应用

gomoku.html

这些引擎在网页端的样子：人机、AI 对战 AI、联机对战与思考研究面板。

更新日志记录

changelog.html

接口与引擎的每次变更都会在这里留痕，排障时先看最近版本。

10模型研发

本站五子棋引擎全部自研，目前注册 6 个模型（Feiyang 3.0 ~ 6.0）。下表目录由 GET /api/v1/gomoku/models 实时拉取，接口不可用时回落到内置目录。

模型目录

服务端注册了 6 个引擎模型。model 参数可以填正式 id，也可以填别名；不填则使用当前默认模型（Feiyang 6.0）。

模型 ID	名称	版本	编号	阶段	别名	说明
加载中…

怎么选

追求棋力：feiyang-v6（默认，对 5.0 胜率 65.6%、对 4.0 84.4%）。
要快 / 做基准对照：feiyang-v3 或 feiyang-v4-stable。
复现历史对局：用当时那版模型（feiyang-v4-preview / feiyang-v5-preview 为归档版本）。
每代模型的架构与评测成绩见模型研发中心。

算力档位

level 决定搜索的时间预算，档位越高越慢也越强。默认 hard；服务端按"软上限"执行，实际耗时会略高于预算（含建模与候选统计）。

level	名称	时间预算	典型耗时	适用场景
加载中…

✓

完整档案在模型研发中心。 每一代引擎的架构、核心改动、横向评测成绩与迭代路线见 models.html；这些引擎在网页里的样子见五子棋对战。

11更新日志

下面内容由页面实时读取仓库根目录的 CHANGELOG.md 渲染，接口、引擎与积分的每次变更都在这里留痕；排障时先看最近几个版本。

飞扬 API 接口 开发文档

00概览

0130 秒上手（以五子棋为例）

02接口总览

03五子棋引擎

接口明细

请求参数

请求示例

响应字段

响应示例

代码示例

在线调试

04中考成绩查询

历年考试场次号（templateId）

05短视频去水印解析

06通用规范

响应包络

错误码

跨域与版本

限流

07注意事项

五子棋 · 坐标系与棋盘

五子棋 · 模型切换

性能与并发

代理型接口（中考 / 短视频）

08常见问题

为什么同一个局面，两次请求结果不一样？

能直接用接口下一整局吗？

value 是胜率吗？

为什么 /llm-move 下的棋比 /move 差？

AI 助手 / 联网搜索的接口在哪？

09相关页面

10模型研发

模型目录

怎么选

算力档位

11更新日志

飞扬 API 接口开发文档

`value` 是胜率吗？

为什么 `/llm-move` 下的棋比 `/move` 差？