API 参考

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

API 地址

https://apiv1.captcha.la

只有一个 API 地址

本页所有接口都在 apiv1.captcha.la 上。备用主机(bypass.*、fallbackapiv1.*)只是 SDK 在主 API 故障时自动切换的兜底目标 —— 把你的集成指向它们会返回 service_online。

认证方式

所有 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 头。

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,用于额外的风控校验;不传也可以。

{
  "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。

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

{
  "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 的请求。

离线兜底端点

主 API 不可用时,CaptchaLa 用一组独立主机上的备用服务维持验证可用:

主机	调用方	用途
bypass.captchala.com · bypass.captcha-cdn.net	Web / 原生 SDK(终端用户侧)	主 API 挂掉期间完成离线验证并签发 offline_ pass token
fallbackapiv1.captchala.com · fallbackapiv1.captcha-cdn.net	服务端 SDK	校验 offline_ token(POST /api/validate)

它们是故障切换目标,不是另一套 API。 SDK 只在主 API 真的失败之后才自行切过去,主 API 恢复后自动切回。你的任何配置都不应该指向它们。

service_online(HTTP 503)

{ "code": -1, "error": "service_online", "message": "Main API is online, please use main API" }

主 API 正常时备用服务不接活 —— 它只在主 API 挂掉时工作。收到这个错误就是请求打到了 bypass.*,改回 https://apiv1.captcha.la 即可,重试没用。

常见原因:

原因	处理
SDK apiServer 配成了 bypass 主机	改回 https://apiv1.captcha.la,或者干脆删掉该配置让 SDK 自己选
手工覆盖了 bypassServers	去掉覆盖(除非我们给了你指定主机)
自研 HTTP 客户端抄了 bypass URL(例如故障期间从 devtools 里复制)	请求 https://apiv1.captcha.la,故障切换交给 SDK;备用服务不接收正常验证流量
负载均衡 / 代理 / DNS 改写了 API 域名	把上游改回 apiv1.captcha.la

TIP

服务端校验同样不需要兜底主机:POST /v1/validate 打 apiv1.captcha.la 即可,PHP / Go 服务端 SDK 遇到 offline_ token 会自动走备用 API。

错误码

错误码	说明
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	该应用的签发请求过于频繁，请稍后重试。
service_online	请求打到了离线兜底服务,而主 API 正常在线。请改用 https://apiv1.captcha.la —— 详见离线兜底端点。