API 参考

CaptchaLa 提供 RESTful API 接口，支持所有功能的服务端调用。

API 地址

https://apiv1.captcha.la

认证方式

所有 API 请求需要在 Header 中携带认证信息：

X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

WARNING

X-App-Secret is server-side only. Never expose it to browsers, mobile apps, or public repos.

服务端验证 API

💡 用服务端 SDK 省去 boilerplate。 封装端点 + 重试 + 类型化错误:
PHP — Captcha-La/captchala-php
Go — go get github.com/Captcha-La/captchala-go · README

在用户通过前端验证码后，您的服务端需要验证 SDK 返回的 Token。以下是服务端验证接口。

服务端验证 Token

验证前端 SDK 返回的 pass_token（前缀为 pt_）。需要携带 X-App-Key 和 X-App-Secret 头。

bash

POST /v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "pt_xxx", "client_ip": "1.2.3.4" }

client_ip 可选，建议传 —— 从你的入站请求里取到的终端用户 IP,用于额外的风控校验;不传也可以。

json

{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "captcha_args": {
      "platform": "web",
      "user_ip": "1.2.3.4",
      "referer": "https://your-site.com/login",
      "pkg": null,
      "solved_at": 1750000000,
      "risk_score": 12
    }
  }
}

TIP

校验 data.valid === true 并且 data.action 与你期望的场景一致(pay 流程的 token 出现在 /login 应拒绝)。Token 单次有效。

captcha_args

captcha_args 回显解题当时记录的上下文,供日志 / 你自己的二次风控:

platform — web / android / ios / flutter / windows / …
user_ip — 解题时看到的终端用户 IP
referer — 解题页面 URL(web);native 为 null
pkg — app 包名 / bundle id(native);web 为 null
solved_at — 解题完成时间(unix 秒)
risk_score — 解题时风险分(0-100,越高越可疑)

服务端签发验证 Token

由您的服务端签发短时效 server_token，再由浏览器在初始化挑战时携带该 Token，从而证明请求来自受信任的服务端。

签发 server_token

仅允许从您的服务端调用。需要 X-App-Key + X-App-Secret。响应返回 server_token（前缀 sct_），前端需在验证初始化时带上该 Token。

bash

POST /v1/server/challenge/issue
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/x-www-form-urlencoded

action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4

json

{
  "code": 0,
  "data": {
    "server_token": "sct_xxxxxxxxxxxx",
    "expires_in": 300,
    "issued_at": 1713600000
  }
}

请求体参数（form-urlencoded）

字段	说明
`action`	业务场景，如 login、register、pay。需与后续验证初始化使用的 action 一致。
`ttl`	Token 有效期（秒）。默认 300，最大 900。
`max_uses`	Token 最大可用次数。默认 10。
`bind_ip`	将 Token 绑定到指定客户端 IP，来自其他 IP 的初始化请求将被拒绝。
`bind_device_id`	将 Token 绑定到指定设备 ID。
`bind_fingerprint`	将 Token 绑定到指定浏览器指纹。

初始化挑战

由 SDK 调用以开始一次验证码挑战。可选参数 server_token 由 /v1/server/challenge/issue 签发。

字段	说明
`app_key`	您的公开 App Key。
`action`	业务场景，需与签发 server_token 时使用的 action 一致。
`server_token`	可选；当应用开启 server_token_required = true 时必填。

INFO

如在控制台为该应用启用了 server_token_required，验证初始化将拒绝所有未携带有效 server_token 的请求。

错误码

错误码	说明
`invalid_app_key`	App Key 无效
`invalid_app_secret`	App Secret 无效
`challenge_expired`	验证码已过期
`challenge_not_found`	验证码不存在
`invalid_answer`	答案错误
`token_expired`	Token 已过期
`token_already_used`	Token 已被使用
`token_not_found`	Token 不存在
`quota_exceeded`	配额已用尽
`rate_limited`	请求频率超限
`rate_limit_exceeded`	该应用的签发请求过于频繁，请稍后重试。

API 参考 ​

API 地址 ​

认证方式 ​

服务端验证 API ​

服务端验证 Token ​

服务端签发验证 Token ​

签发 server_token ​

请求体参数（form-urlencoded） ​

初始化挑战 ​

错误码 ​