接入 API 文档

面向网站接入方：如何嵌入验证码、拿到一次性凭证，并在你自己的服务器上完成核验。

当前服务地址 https://your-host

快速开始

  1. 注册并创建项目：在控制台拿到公开钥匙（site_key）与服务端密钥（secret）。
  2. 页面嵌入 Widget：只用 site_key；用户完成挑战后得到 verification_token。
  3. 随业务请求提交凭证：和登录、注册等表单一起发到你的后端。
  4. 服务端调用 siteverify：用 secret 向本服务确认 token 有效后，再放行业务。
浏览器只放 site_key（pk_…）。secret（sk_…）只能放在你的后端，切勿写进前端或公开仓库。

前端嵌入

在需要验证的页面引入脚本与容器（地址会自动使用当前域名）：


      
或使用 JavaScript：

      

      
成功后隐藏字段 vc-response 会带上 verification_token；也可在 onSuccess 回调里拿到。

      
全局对象为 PrivaCaptcha（旧名 VerifyCode 仍可用）。


      
浏览器 API

      
一般由 Widget 自动调用，手动对接时可用。


      
POST/v1/widget/challenge

      
签发挑战。答案明文不会出现在响应中。

      
{
  "site_key": "pk_...",
  "type": "slideshine",
  "preset": "readable",
  "visual_mode": "motion",
  "locale": "zh"
}

      

        
          
字段说明

        
        
          
site_key必填。控制台项目的公开钥匙。

          
type可选。验证类型；缺省用站点默认引擎，且须在站点允许列表内。

          
visual_mode可选。motion（默认）或 flicker。

          
locale / lang可选。zh 或 en；也可用 Accept-Language。

          
preset输入型可用：readable（默认）/ strict。

        
      

      
成功响应含 challenge_id、expires_in、engine、params（渲染参数）、以及站点的 allowed_engines。


      
POST/v1/widget/verify

      
提交用户答案，换取一次性 verification_token。

      
{
  "site_key": "pk_...",
  "challenge_id": "uuid",
  "answer": "..."
}

      
{
  "success": true,
  "verification_token": "uuid"
}


      
服务端核验

      
POST/v1/siteverify

      
在你的后端调用（勿在浏览器调用）。Token 一次性有效。

      
{
  "secret": "sk_...",
  "response": "<verification_token>"
}

      
也支持 application/x-www-form-urlencoded：字段 secret + response。

      


      
外观（主题 / 皮肤 / 尺寸）

      
只改 Widget 外壳，不影响挑战画布强度。

      

        
          

            参数
            HTML
            JS
            取值
          

        
        
          

            主题
            data-theme
            theme
            dark / light / auto
          

          

            皮肤
            data-skin
            skin
            default / soft / sharp / minimal / compact
          

          

            尺寸
            data-size
            size
            normal / compact / large
          

        
      

      
优先级：页面显式参数 → 站点 engine_config 默认 → dark / default / normal。可用 setAppearance() 运行时切换。


      
验证类型

      
用 type 指定，或使用控制台配置的默认引擎与允许列表。新建项目默认提供滑块 + 输入两种，便于访客切换。

      

        
          
type说明

        
        
          
slideshine滑块拼图（推荐默认）

          
temporalfreq输入字符

          
flashclick选项点选

          
pulsepick点选可见字形砖块

          
driftmatch形状匹配（多选一）

          
shapeflash形状问答

        
      

      
视觉模式：motion（默认，动态纹理）或 flicker（闪烁）。旧客户端若传 crossflow，会按 temporalfreq + motion 处理。


      
API Key 模式（服务间）

      
适合服务端直接签发/校验挑战（非浏览器 Widget 流程）。请求头：

      
X-API-Key: vc_...

      

      
常见错误

      

        
          
情况说明

        
        
          
跨域 / Origin请在控制台为项目配置允许的域名；生产环境建议开启严格 Origin。

          
token 无效verification_token 已使用、过期或 secret 不匹配。

          
答案错误挑战通常仅一次机会；失败后需重新 challenge。

          
限流请求过于频繁时返回限流错误，稍后重试。

        
      

      
GET/healthz — 存活探测（运维探活用）。