开发者文档

API 文档

快速接入薯芯云人机验证系统

快速开始

三步完成接入

1

注册账号并创建应用

注册薯芯云账号，在控制台创建应用，获取 AccessKey ID 和 AccessKey Secret

2

引入SDK

<script src="https://yz.sxyun.cloud/sdk/captcha.js"></script>
3

初始化验证

ShuxinCaptcha.init({
    accessKey: 'sk_live_xxx',
    scene: 'login',
    element: '#captcha-btn',
    onSuccess: function(data) {
        console.log('验证通过', data.token);
    }
});

API接口

完整的接口说明

POST /captcha_init.php 获取验证码

请求头

Authorization: Bearer {AccessKey}
Content-Type: application/json

请求参数

参数名类型必填说明
scenestring是验证场景（login/register/pay/comment）

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "captcha_id": "ct_abc123...",
    "numbers": [5, 2, 8, 1, 9, 3],
    "expire": 60
  }
}
POST /captcha_verify.php 校验验证结果

请求头

Authorization: Bearer {AccessKey}
Content-Type: application/json

请求参数

参数名类型必填说明
captcha_idstring是验证码ID
click_orderarray是点击顺序数组

响应示例

{
  "code": 200,
  "msg": "验证通过",
  "data": {
    "success": true,
    "token": "a1b2c3d4..."
  }
}

错误码说明

错误码说明解决方案
200请求成功-
400参数错误或验证失败检查请求参数
401缺少AccessKey添加Authorization头
402余额不足充值或购买套餐
403无效的AccessKey检查密钥是否正确
404验证码不存在重新获取验证码
409验证码已使用重新获取验证码
410验证码已过期重新获取验证码

SDK示例

// JavaScript 示例
ShuxinCaptcha.init({
    accessKey: 'sk_live_xxx',
    scene: 'login',
    element: '#captcha-btn',
    onSuccess: function(data) {
        console.log('验证通过', data.token);
        // 将token提交到后端
    }
});
# Python 示例
import requests

# 获取验证码
response = requests.post(
    "https://yz.sxyun.cloud/captcha_init.php",
    headers={"Authorization": "Bearer sk_live_xxx"},
    json={"scene": "login"}
)
captcha_data = response.json()

# 校验验证码
verify_response = requests.post(
    "https://yz.sxyun.cloud/captcha_verify.php",
    headers={"Authorization": "Bearer sk_live_xxx"},
    json={
        "captcha_id": captcha_data["data"]["captcha_id"],
        "click_order": [1, 2, 3, 5, 8, 9]
    }
)
result = verify_response.json()
// PHP 示例
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://yz.sxyun.cloud/captcha_init.php");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer sk_live_xxx",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["scene" => "login"]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
// Java 示例
OkHttpClient client = new OkHttpClient();

String json = "{\"scene\":\"login\"}";
RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));

Request request = new Request.Builder()
    .url("https://yz.sxyun.cloud/captcha_init.php")
    .addHeader("Authorization", "Bearer sk_live_xxx")
    .post(body)
    .build();

Response response = client.newCall(request).execute();
// Go 示例
package main

import (
    "bytes"
    "net/http"
)

func main() {
    json := []byte(`{"scene":"login"}`)
    req, _ := http.NewRequest("POST", "https://yz.sxyun.cloud/captcha_init.php", bytes.NewBuffer(json))
    req.Header.Set("Authorization", "Bearer sk_live_xxx")
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

常见问题

如何获取API密钥？

注册账号后，在控制台创建应用，即可获取AccessKey ID和AccessKey Secret。

验证码有效期是多久？

验证码默认有效期为60秒，超时后需要重新获取。

如何设置IP白名单？

在应用管理页面，编辑应用时可以设置IP白名单，限制API调用来源。