Server

After the user completes the challenge on the Client, you can obtain a response string in the following ways:

• When the user submits via the form, the aicaptcha-response POST parameter
• After the user completes the challenge, use aiCaptcha.getResponse(widgetId) method to obtain
• If data-callback is specified in the aicaptcha tag attribute or in the callback parameter of the aiCaptcha.render method, obtain it through the callback function string parameter

You need to pass this string to your server, and then send it to AICaptcha's server from your server for server-side verification, in order to finally confirm whether this challenge is successful.

Endpoint

https://api1.aicaptcha.net/siteverify

HTTP Method

POST

Content Type

application/x-www-form-urlencoded

Parameters

Parameter	Required	Description
secret	Required	Your site key, which can be obtained from the management console, please note that it needs to match the site used when integrating on the Client.
response	Required	The aforementioned response string
remote_ip	Optional	Customer's IP Address. This is not mandatory, in certain subscription versions, passing this parameter helps refine some IP policies and obtain additional response information.

Please note that the HTTP method received by the server-side verification API is POST, and the request format is application/x-www-form-urlencoded, and all request parameters are in the request body.

A simple example is as follows:

curl -X POST 'https://api1.aicaptcha.net/serververify' \
--header 'Content-Type: application/x-www-form-urlencoded' \
-d 'secret=YOUR_SECRET&response=YOUR_RESPONSE&remote_ip=YOUR_REMOTE_IP' 

Response

The response format of the API is application/json.

If your call is successful, you will receive a response with the status field set to "success", like:

{
    "result": "success",
    "reason": "",
    "status": "success"
}

You need to focus on whether the returned value of the result field is "success". If it is "success", it means that this verification has passed; otherwise, it means that the verification result has failed, and in this case, the reason field will return the reason for the failed verification.

If your call fails, you will receive a response with the status field set to "error", like:

{
    "status": "error",
    "code": "decrypt_fail",
    "err_msg": "parameter decryption failed"
}

In this case, the code field and err_msg field will return some error messages to help you resolve issues that occur during server-level validation. You can refer to the Server Error Code Document for more information.

Backend Example

We have provided some simple examples. Although we will not provide examples for all languages, this may be very helpful in assisting you to understand how to correctly call the server-side verification API.

Python

import requests
import traceback

ENDPOINT = "https://api1.aicaptcha.net/serververify"
SECRET = "YOUR_SECRET"

def server_verify(client_resp, remote_ip=None):
    data = {
        "secret": SECRET,
        "response": client_resp,
        "remote_ip": remote_ip,
    }
    try:
        resp = requests.post(ENDPOINT, data=data).json()
    except:
        # TODO: handle different exceptions
        print("Server verification failed:", traceback.format_exc())
        return
    if resp.get("status") != "success":
        print(
            "Server verification failed, code:",
            resp.get("code"),
            "err_msg:",
            resp.get("err_msg"),
        )
    else:
        if resp.get("result") == "success":
            print("Server verification successful: valid client response")
        else:
            print(
                "Server verification successful, but invalid client response, reason:",
                resp.get("reason"),
            )

if __name__ == "__main__":
    server_verify("YOUR_RESPONSE")

Java

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;

public class aicaptchaServerVerify {
    private static final String ENDPOINT = "https://api1.aicaptcha.net/serververify";
    private static final String SECRET = "YOUR_SECRET";
    
    public static void serverVerify(String clientResp, String remoteIp) {
        try {
            // Build request body
            String requestBody = String.format("secret=%s&response=%s&remote_ip=%s", 
                SECRET, clientResp, remoteIp != null ? remoteIp : "");
            
            // Create HTTP client and request
            HttpClient client = HttpClient.newHttpClient();
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(ENDPOINT))
                .header("Content-Type", "application/x-www-form-urlencoded")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();
            
            // Send request and get response
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            
            // Parse JSON response
            ObjectMapper mapper = new ObjectMapper();
            Map<String, Object> resp = mapper.readValue(response.body(), Map.class);
            
            // Check response status
            if (!"success".equals(resp.get("status"))) {
                System.out.println("Server verification failed, code: " + resp.get("code") + 
                    ", err_msg: " + resp.get("err_msg"));
            } else {
                if ("success".equals(resp.get("result"))) {
                    System.out.println("Server verification successful: valid client response");
                } else {
                    System.out.println("Server verification successful, but invalid client response, reason: " + 
                        resp.get("reason"));
                }
            }
            
        } catch (Exception e) {
            System.out.println("Server verification failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
    
    public static void main(String[] args) {
        serverVerify("YOUR_RESPONSE", null);
    }
}