API 参考
API 指南
完整的 API 接口文档
客户端 SDK
服务端接口
快速导航
初始化接口
不同平台的初始化方法：
| 平台 | 初始化方法 | 文档链接 |
|---|---|---|
| Web | initGeetest4(config, callback) | Web API |
| iOS | GeeLabCaptchaSession.sessionWithCaptchaID() | iOS API |
| Android | GeelabCaptchaClient.getClient().init() | Android API |
二次校验接口
服务端验证接口：
| 项目 | 内容 |
|---|---|
| 接口地址 | 请根据您注册 ID 时选择的地域使用对应域名： 全球： https://cap-global.geelabapi.com/validate欧洲： https://cap-eu.geelabapi.com/validate北美： https://cap-na.geelabapi.com/validate |
| 请求方法 | GET/POST（推荐 POST） |
| 请求格式 | application/x-www-form-urlencoded |
| 返回类型 | JSON |
重要： 必须在服务端进行二次验证，不要仅依赖客户端结果。
详细文档请查看 Server API。
核心参数
captcha_id
验证公钥 - 32 位字符串，从极验后台获取。
// Web 示例
initGeetest4({
captchaId: 'YOUR_CAPTCHA_ID'
}, callback);captcha_key
验证私钥 - 32 位字符串，仅在服务端使用。
切勿在客户端代码中暴露 captcha_key。
# 服务端示例
CAPTCHA_KEY = 'YOUR_CAPTCHA_KEY' # 从环境变量读取验证结果参数
客户端验证成功后返回的参数：
| 参数 | 说明 |
|---|---|
lot_number | 验证流水号 |
captcha_output | 验证输出信息 |
pass_token | 验证通过标识 |
gen_time | 验证通过时间戳 |
这些参数需要提交到服务端进行二次验证。
返回码与错误处理
客户端错误码
常见的客户端错误码：
| 错误码 | 说明 |
|---|---|
60001 | 配置参数 captcha_id 有误 |
60100 | /load 请求报错 |
60200 | 皮肤加载失败 |
完整错误码列表请查看各平台的 API 文档。
服务端错误码
常见的服务端错误码：
| 错误码 | 说明 |
|---|---|
-50005 | gen_time 参数异常 |
-50103 | 不存在的验证 ID |
-50301 | 流水号信息不存在 |
完整错误码列表请查看 Server API。
请求示例
客户端初始化
以下是各平台的基本初始化示例，详细配置请查看对应平台的 API 文档。
Web:
initGeetest4({
captchaId: 'YOUR_CAPTCHA_ID',
product: 'bind'
}, function(captchaObj) {
captchaObj.onSuccess(function() {
const result = captchaObj.getValidate();
// 提交到服务端验证
});
});iOS:
GeeLabCaptchaSession *session = [GeeLabCaptchaSession
sessionWithCaptchaID:@"YOUR_CAPTCHA_ID"];
session.delegate = self;
[session verify];Android:
GeelabCaptchaClient client = GeelabCaptchaClient.getClient(activity)
.init("YOUR_CAPTCHA_ID", config);
client.verifyWithCaptcha();服务端验证
Python 快速示例：
import hmac
import hashlib
import requests
# 生成签名
sign_token = hmac.new(
CAPTCHA_KEY.encode(),
lot_number.encode(),
hashlib.sha256
).hexdigest()
# 发起验证请求
response = requests.post(
'https://cap-global.geelabapi.com/validate',
params={'captcha_id': CAPTCHA_ID},
data={
'lot_number': lot_number,
'captcha_output': captcha_output,
'pass_token': pass_token,
'gen_time': gen_time,
'sign_token': sign_token
}
)完整的服务端验证实现请参考：
- 服务端集成指南 - 集成步骤和最佳实践
- Server API 文档 - 完整的 API 参数和多语言代码示例
下一步
- 查看 Web API 了解 Web SDK 详细配置
- 查看 Server API 了解服务端验证接口
- 阅读 部署指南 了解集成流程
- 查看 常见问题 解决集成问题