Go 服务端 SDK

官方 Go 服务端 SDK —— github.com/Captcha-La/captchala-go。

SDK 帮你做三件事：

1. 校验（Validate）—— 验证浏览器 SDK 返回的 pt_ pass token。
2. 签发（Issue）—— 签发一次性 sct_ server token, 将本次挑战绑定到具体 action / IP / UID。
3. 审核（Moderate）—— 多模态（文本 + 图片）内容审核, 走 dashboard 同款 OpenAI 兼容管道。

安装

go get github.com/Captcha-La/captchala-go

只用标准库, 无外部依赖。

校验（pt_ token）

import captchala "github.com/Captcha-La/captchala-go"

client := captchala.NewClient(appKey, appSecret)

result, err := client.Validate(passToken)
if err != nil || !result.Valid {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}
// 继续业务流程

如果原 server_token 带了 bind_uid, 校验时核对 uid：

if result.UID != expectedUserID {
    http.Error(w, "user mismatch", http.StatusBadRequest)
    return
}

IP 绑定的 token, 校验时也传用户 IP：

result, err := client.ValidateWithClientIP(passToken, false, userIP)

签发 server token

注册 / 登录 / 支付等高价值场景推荐流程：后端签发一次性 sct_ token, 下发给前端, 浏览器作为 serverToken 用。单次消费, 绑定 action, 可选绑定 IP / UID。

issue, err := client.IssueServerTokenWithOptions("login", captchala.IssueOptions{
    BindingIP: userIP,    // 不同 IP 来兑换会被拒
    TTL:       300,       // 秒
    MaxUses:   5,         // SDK 重试预算
    BindUID:   userID,    // 配合 ValidateResult.UID 校验
})
if err != nil || !issue.OK {
    http.Error(w, issue.Error, http.StatusBadRequest)
    return
}
// 把 issue.Token 下发给浏览器

默认参数快捷方式：

issue, err := client.IssueServerToken("login")

内容审核

多模态 —— 接受 ModerationItem 切片（文本 / image_url 混合, OpenAI 兼容）：

result, err := client.ModerationCheck([]captchala.ModerationItem{
    captchala.TextItem(userComment),
    captchala.ImageURLItem(uploadedImageURL),
}, userID)

if err != nil || !result.OK {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}

if result.Flagged {
    if result.HasCategory("violence", "csam") {
        // 硬阻断
    }
}

纯文本快捷方式：

result, err := client.ModerationText("user comment here", userID)

Category 列表由上游模型决定, 用 result.Categories 防御性遍历, 不要硬编码固定集合。

类型

类型	字段
ValidateResult	Valid、Error、UID、ChallengeID、Action、Offline、ClientOnly、Warning
IssueResult	OK、Token、ExpiresIn、IssuedAt、Error、Message
IssueOptions	BindingIP、TTL、MaxUses、BindUID
ModerationItem	Type、Text、ImageURL（用 TextItem() / ImageURLItem() 辅助函数构造）
ModerationResult	OK、Flagged、Categories、ContentType、Raw、Error、Message；方法 HasCategory(...names)

链接

• pkg.go.dev · GitHub
• Web SDK 总览 · API 参考