小影API 小影API

图形验证

阿里云图形验证码集成（滑块/点选等），服务端下发配置并二次校验，防机器流量。当前接入阿里云线路。

/api/captcha_auth/

服务说明

图形验证服务集成阿里云图形验证码（滑块、点选等行为验证），用于在注册、登录、发短信等入口拦截机器流量：前端先用配置接口拿到 appId 初始化 SDK 并完成验证，再把验证参数交给业务后端调用核验接口，确认本次验证真实有效。

为避免被绕过，验证结果必须在服务端二次核验，不能只依赖前端回调。

该线路整体为开放接口，config 与 verify 均无需项目签名，便于前端直接集成。

响应格式

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

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

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

阿里云图形认证

阿里云图形认证服务（滑块/点选验证） 开放 · 免签名

两步接入：先用 config 拿 appId 初始化前端 SDK，用户验证通过后再用 verify 做服务端二次校验。

GET /api/captcha_auth/aliyun/config 累计调用 19 次

获取图形认证配置

返回图形认证 appId（captchaId），供 H5 前端 SDK 初始化。公开接口，无需签名。

  • 响应 data.app_id 即前端 initAlicom4({ captchaId: app_id, product: "bind" }, ...) 所需的 captchaId。
响应说明 外层统一格式
字段 类型 说明
app_id string 图形认证 appId（captchaId）
返回示例 
{"app_id": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"}
POST /api/captcha_auth/aliyun/verify 累计调用 10 次

二次校验

上传客户端验证参数，确认用户本次图形验证有效（防绕过）。

必填：前端 SDK 验证通过后回调返回的流水号，32 位小写 hex

必填：前端 SDK 验证通过后回调返回的 captchaOutput

必填：前端 SDK 验证通过后回调返回的 passToken

必填：前端 SDK 验证通过后回调返回的 genTime

  • 请求体为 application/x-www-form-urlencoded 表单；公开接口，无需项目签名。
  • 接口请求成功统一返回 code=10000；业务结果以 data.result 判断：
  • success=验证有效，fail=验证无效（pass_token 过期/流水号已用等），原因见 data.reason。
响应说明 外层统一格式
字段 类型 说明
result string 校验结果：success/fail
passed bool 是否校验通过
reason string 失败原因（成功为空）
captcha_args object 验证输出参数（风控信息）
返回示例 
{"result": "success", "passed": true, "reason": "", "captcha_args": {}}

图形验证 API 常见问题

图形验证怎么接入？
两个端点：config 下发前端初始化配置，前端渲染滑块 / 点选；用户通过后拿到凭证，再调 verify 在服务端二次校验，只有二次校验通过才放行业务请求。
为什么必须做二次校验？
前端通过只说明浏览器侧完成了挑战，凭证本身可被伪造或重放；服务端校验才能挡住脚本绕过页面直接调业务接口。
和自研图形验证码有什么区别？
这条线路是阿里云托管的人机验证，不需要自己维护题库与图片；自研那条是本地 Pillow 绘制（字符 / 算术 / 滑块 / 点选），见「自研图形验证码」服务。
图形验证接口怎么接入？需要签名吗？
图形验证挂在 /api/captcha_auth/ 前缀下：需签名的端点按 app_id + timestamp + nonce + sign（HMAC-SHA256，密钥为 APPSECRET）调用，开放端点直接请求即可。拿不准时用本页右侧的「在线调试」—— 它会代签并把你实际发出的请求与真实响应都回显出来。
图形验证的返回结构和错误码怎么看？
全部接口统一返回 {code, msg, data}：code=10000 表示成功，2xxxx 为业务错误，3xxxx / 4xxxx / 5xxxx 分别为外部依赖、客户端与系统错误。完整含义与处理建议见「错误码总表」（/docs/errors/）。
小影API · 通用 API 聚合服务