自研图形验证码

自研图形验证码（字符图片 / 算术），Pillow 本地绘制、无第三方依赖，答案一次性校验。

/api/captcha_self/

服务说明

自研图形验证码不依赖任何第三方服务，由平台用 Pillow 在本地绘制字符图片或算术题，适合对数据外发敏感、或希望零成本自建验证码的场景。

接入为两步：先调用生成接口拿到 captcha_id 与 base64 图片（带有效期），用户作答后调用校验接口提交答案。答案是「一次性」的——无论校验成功还是失败都会立即失效，失败后需重新生成再试。服务端只保存答案的 HMAC-SHA256 摘要，不落明文。

该线路为开放接口，无需项目签名；服务端已按客户端 IP 限流（生成 60 次/分、校验 120 次/分），并在响应上禁用缓存，避免图片被浏览器 / 代理复用。

同一服务下另有「滑块验证」与「汉字点选」线路：前者拖动拼图块对齐缺口，后者按提示依次点击 2-4 个汉字；两者的答案坐标都不下发，只存服务端用于校验。

三条线路怎么选：表单防刷优先字符 / 算术（生成快、体积小）；想要拖动体验用滑块；面向中文用户、希望更直观可以用汉字点选。

响应格式

所有接口返回同一个 JSON 信封，业务数据都在 data 里：

{
  "code": 10000,
  "msg": "成功",
  "data": { ... }
}

code：业务状态码，10000 表示成功；其余为各类错误，完整清单见「错误码」页。
msg：给人看的提示文案，可直接展示给终端用户，但不要用它做逻辑判断。
data：业务数据；出错时通常为 null。各接口 data 的具体字段见该接口的「响应说明」。

判断成功与否请看 code，不要依赖 HTTP 状态码。查看完整错误码

自研验证码

SpiderServices/Captcha 自研生成引擎（Pillow 绘制）开放 · 免签名

两步接入：先 generate 拿 captcha_id 与图片（base64），用户作答后 POST verify 校验；答案一次性，校验后无论对错立即失效，需配合前端换新图。

GET /api/captcha_self/generate 累计调用 398 次

生成验证码

生成一张验证码，返回 captcha_id、base64 图片与有效期。

验证码类型 kind

选填：char=字符图片（数字+大写字母）；arithmetic=算术加减法

字符个数 length

选填：仅 kind=char 生效，取值 4-6（默认 4）

请求方式 GET，参数放 query string；公开接口，无需项目签名。
captcha_id 必须与答案一起回传给 verify；image 可直接用作 <img src>。
响应头带 Cache-Control: no-store，图片不会被浏览器 / 代理缓存复用。
同一 IP 每分钟最多生成 60 张，超出返回 20040。

响应说明外层统一格式

字段	类型	说明
captcha_id	string	验证码ID，校验时回传
kind	string	类型：char/arithmetic
image	string	base64 图片（data URI）
expire_in	int	有效期（秒）

返回示例

{"captcha_id": "9f1c1f14-6b0a-4a3e-9c31-2c9b6f0d1a55", "kind": "char", "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...", "expire_in": 300}

POST /api/captcha_self/verify 累计调用 52 次

校验验证码

提交用户答案校验，一次性消费（校验后立即失效）。

验证码ID captcha_id *

必填：生成接口返回的 captcha_id（UUID）

用户答案 answer *

必填：用户填写的答案（字符不区分大小写；算术填计算结果）

请求体为 application/x-www-form-urlencoded 表单；开放接口，无需项目签名。
校验通过：code=10000 且 data.passed=true；
未通过（答案错误 / 已过期 / 已使用 / 不存在）：code=20003 且 data.passed=false，原因见 msg；
captcha_id 非 UUID 时返回 code=20002，参数缺失时返回 code=20001。
答案一次性：同一条验证码重复提交只会成功一次，失败后需重新调用 generate。
同一 IP 每分钟最多校验 120 次，超出返回 20040；答案用恒定时间比较，库中只存摘要。

响应说明外层统一格式

字段	类型	说明
passed	bool	是否校验通过

返回示例

{"passed": true}

滑块验证

Pillow 本地合成（背景图 + 拼图块）开放 · 免签名

拖动拼图块对齐缺口；缺口横坐标不下发，服务端按 ±8px 容差比对摘要，并校验拖动轨迹（点数 / 时长 / 时间单调 / 终点一致）。

GET /api/captcha_self/slider/generate 累计调用 149 次

生成滑块

生成背景图与拼图块，返回 slider_id、纵坐标与画布尺寸。

拖动体验

请求方式 GET，公开接口，无需项目签名。
background 为 JPEG、piece 为 PNG（均为 data URI）；缺口横坐标不在响应里，必须由用户拖动拼图块对齐。
同一 IP 每分钟最多生成 30 张，超出返回 20040；响应禁止缓存。

响应说明外层统一格式

字段	类型	说明
slider_id	string	滑块ID，校验时回传
background	string	背景图（JPEG data URI）
piece	string	拼图块（PNG data URI，透明背景）
piece_y	int	拼图块纵向位置（像素）
piece_size	int	拼图块边长（像素）
width	int	画布宽度（像素，320）
height	int	画布高度（像素，160）
expire_in	int	有效期（秒）

返回示例

{"slider_id": "9f1c1f14-6b0a-4a3e-9c31-2c9b6f0d1a55", "background": "data:image/jpeg;base64,/9j/4AAQ…", "piece": "data:image/png;base64,iVBORw0KGgo…", "piece_y": 42, "piece_size": 52, "width": 320, "height": 160, "expire_in": 180}

POST /api/captcha_self/slider/verify 累计调用 25 次

校验滑块

提交拼图块位置与拖动轨迹，一次性校验。

滑块ID slider_id *

必填：生成接口返回的 slider_id（UUID）

横向位置 x *

必填：拼图块左边缘的画布横坐标（可带小数）

拖动轨迹 track *

必填：JSON 数组，元素为 {"x": 画布坐标, "t": 相对毫秒}；至少 5 个点，总时长 200ms-60s，终点须与 x 一致

请求体为 application/x-www-form-urlencoded 表单；公开接口，无需项目签名。
位置误差 ±8px 内视为对齐；缺口横坐标不下发，库中只存摘要。
轨迹点数不足 / 用时过短 / 时间倒退 / 终点与 x 不一致都会被拒绝。
一次性：无论成功失败，同一 slider_id 只能校验一次。
同一 IP 每分钟最多校验 60 次；连续失败 10 次冷却 10 分钟，两种拦截都返回 20040。

响应说明外层统一格式

字段	类型	说明
passed	bool	是否校验通过

返回示例

{"passed": true}

汉字点选

Pillow + 内置中文字体（8 个候选汉字，点选 2-4 个）开放 · 免签名

按提示依次点击目标汉字；目标坐标不下发，服务端校验点击顺序、命中位置与总用时。

GET /api/captcha_self/click/generate 累计调用 15 次

生成点选验证码

生成一张含 8 个候选汉字的图片，返回挑战ID、图片与目标字顺序。

点选体验

请求方式 GET，公开接口，无需项目签名。
chars 是按顺序需要点击的目标字（2-4 个）；每个字的坐标不在响应里，服务端只落库用于命中判断。
同一 IP 每分钟最多生成 30 张，超出返回 20040；响应禁止缓存。

响应说明外层统一格式

字段	类型	说明
challenge_id	string	挑战ID，校验时回传
image	string	验证码图片（PNG data URI）
chars	array	按顺序需要点击的目标汉字
count	int	目标字个数（2-4）
width	int	画布宽度（像素，360）
height	int	画布高度（像素，200）
expire_in	int	有效期（秒）

返回示例

{"challenge_id": "9f1c1f14-6b0a-4a3e-9c31-2c9b6f0d1a55", "image": "data:image/png;base64,iVBORw0KGgo…", "chars": ["山", "河", "云"], "count": 3, "width": 360, "height": 200, "expire_in": 180}

POST /api/captcha_self/click/verify 累计调用 3 次

校验点选

提交按顺序的点击点，校验顺序、命中位置与总用时。

挑战ID challenge_id *

必填：生成接口返回的 challenge_id（UUID）

点击点 points *

必填：JSON 数组，元素为 {"x": 画布横坐标, "y": 画布纵坐标, "t": 相对毫秒}；点数须等于 count，总时长不少于 300ms

请求体为 application/x-www-form-urlencoded 表单；公开接口，无需项目签名。
点击顺序必须与 chars 一致；每个点需落在对应目标字半径 26px 内。
点数不符 / 顺序错 / 点偏 / 总用时不足 300ms 都会被拒绝。
一次性：无论成功失败，同一 challenge_id 只能校验一次。
同一 IP 每分钟最多校验 60 次；连续失败 10 次冷却 10 分钟，两种拦截都返回 20040。

响应说明外层统一格式

字段	类型	说明
passed	bool	是否校验通过

返回示例

{"passed": true}

接口目录 6

自研验证码

GET 生成验证码 /api/captcha_self/generate POST 校验验证码 /api/captcha_self/verify

滑块验证

GET 生成滑块 /api/captcha_self/slider/generate POST 校验滑块 /api/captcha_self/slider/verify

汉字点选

GET 生成点选验证码 /api/captcha_self/click/generate POST 校验点选 /api/captcha_self/click/verify

鉴权设置

仅本机保存

自研图形验证码 API 常见问题

自研验证码有哪几种？

三类：字符 / 算术图片（生成 + 校验）、滑块（生成 + 校验）、汉字点选（生成 + 校验），每种都是「拿图 → 用户作答 → 服务端校验」两步。

为什么不依赖第三方？

图片全部由服务端用 Pillow 本地绘制，不需要接任何验证码厂商账号，也不受外网可用性影响，适合内网或成本敏感的项目。

校验是一次性的吗？

是。每个验证码对应一个一次性标识，校验成功即作废，重复使用会失败，防止同一个码被复用。

有现成的前端示例吗？

有，本站 /captcha_self/slider/ 与 /captcha_self/click/ 两个演示页就是完整前端实现，拖动 / 点选的交互与校验流程可直接照搬。

自研图形验证码接口怎么接入？需要签名吗？

自研图形验证码挂在 /api/captcha_self/ 前缀下：需签名的端点按 app_id + timestamp + nonce + sign（HMAC-SHA256，密钥为 APPSECRET）调用，开放端点直接请求即可。拿不准时用本页右侧的「在线调试」—— 它会代签并把你实际发出的请求与真实响应都回显出来。

自研图形验证码的返回结构和错误码怎么看？

全部接口统一返回 {code, msg, data}：code=10000 表示成功，2xxxx 为业务错误，3xxxx / 4xxxx / 5xxxx 分别为外部依赖、客户端与系统错误。完整含义与处理建议见「错误码总表」（/docs/errors/）。