Skip to content
CaptchaSonic

SDK Java

SDK Java chính thức cho CaptchaSonic — truyền tải nhị phân gRPC, an toàn đa luồng, bất đồng bộ với CompletableFuture.

SDK Java chính thức cho API giải CAPTCHA CaptchaSonic.

Truyền tải

Sử dụng gRPC gốc qua grpc-netty-shaded. Ảnh được gửi dưới dạng nhị phân thô — không có chi phí base64.

Cài đặt

Gradle

implementation 'com.captchasonic:captchasonic:1.0.0'

Maven

<dependency>
    <groupId>com.captchasonic</groupId>
    <artifactId>captchasonic</artifactId>
    <version>1.0.0</version>
</dependency>

Bắt đầu nhanh

import com.captchasonic.CaptchaSonicClient;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

try (var client = new CaptchaSonicClient("sonic_your_api_key")) {
    double balance = client.getBalance();
    System.out.println("Balance: $" + balance);

    byte[] tile = Files.readAllBytes(Path.of("tile.png"));
    var result = client.solvePopularCaptcha(
        List.of(tile), "Select all traffic lights", "objectClassify"
    );
    System.out.println(result.getTypedSolution().getGrid().getObjectsList());
}

Builder Pattern

CaptchaSonicClient client = CaptchaSonicClient.builder()
    .apiKey("sonic_xxx")
    .host("api.captchasonic.com")
    .port(443)
    .timeout(Duration.ofSeconds(120))
    .build();

Endpoint tùy chỉnh

var client = new CaptchaSonicClient("sonic_xxx", "api.captchasonic.com", 443, true);

Client này an toàn với đa luồng — hãy tạo một instance và tái sử dụng.


Bộ giải ảnh

solvePopularCaptcha()

client.solvePopularCaptcha(images, question, questionType);

// Full options
client.solvePopularCaptcha(
    images,                          // List<byte[]>
    "Select all traffic lights",     // question
    "objectClassify",                // questionType
    exampleImages,                   // List<byte[]>, nullable
    false,                           // screenshot
    "https://example.com",           // websiteUrl, nullable
    "sitekey123"                     // websiteKey, nullable
);

solveRecaptchaV2()

client.solveRecaptchaV2(images, "traffic lights");

// With questionType + options
client.solveRecaptchaV2(
    images,                   // List<byte[]>
    "traffic lights",         // question
    "split_33",               // questionType: "split_33" | "33" | "44"
    "https://example.com",    // websiteUrl, nullable
    null                      // websiteKey, nullable
);

solveGeetest()

client.solveGeetest("geetest_nine:Select the bear", images);

// Full options
client.solveGeetest(question, images, examples, bgImage, gtv, websiteUrl);

solveOcr()

client.solveOcr(images);

// With options
client.solveOcr(images, "mtcaptcha", false, false, 3, 4, "https://example.com");

solveTikTok()

// Type-based routing (alias expansion built-in)
client.solveTikTok("whirl", "Rotate to match", images);
client.solveTikTok("click", "Select the shape", images, examples, websiteUrl);
// Accepted types: "click", "whirl", "slide", "tiktok_click", etc.

solveBinance()

client.solveBinance("grid", "Select the bicycle", images);
client.solveBinance("slide", "", images, examples, websiteUrl);
// Accepted types: "grid", "slide", "binance_grid", "binance_slide"

solveAwsWaf()

client.solveAwsWaf(images, "grid:vehicles:cars");
client.solveAwsWaf(images, question, websiteUrl, websiteKey);

solveSlideImage()

client.solveSlideImage(List.of(background, piece));
// Returns: result.getTypedSolution().getSlide().getX()

Các phương thức tự động hóa token

Các phương thức này gửi tác vụ và thăm dò cho đến khi nhận được token (tối đa 120 giây).

client.solveTurnstile(websiteUrl, websiteKey);
client.solveTurnstile(websiteUrl, websiteKey, proxy);
client.solvePopularCaptchaToken(websiteUrl, websiteKey, proxy);
client.solveRecaptchaV2Token(websiteUrl, websiteKey, proxy);
client.solveRecaptchaV3Token(websiteUrl, websiteKey, proxy);
client.solveCloudflare(websiteUrl, websiteKey, proxy);  // proxy required

Mọi phương thức chặn (blocking) đều có biến thể Async trả về CompletableFuture<CreateTaskResponse>.


Các phương thức tiện ích

double balance = client.getBalance();
HealthCheckResponse health = client.healthCheck();
GetTaskResultResponse result = client.getTaskResult(taskId);

Xử lý lỗi

import com.captchasonic.*;

try {
    client.solvePopularCaptcha(images, question, questionType);
} catch (InvalidApiKeyException e)       { /* errorId=1 */ }
  catch (InsufficientBalanceException e) { /* errorId=2 */ }
  catch (DailyLimitExceededException e)  { /* errorId=3 */ }
  catch (MinuteLimitExceededException e) { /* errorId=4 */ }
  catch (QuotaExceededException e)       { /* errorId=5 */ }
  catch (PlanExpiredException e)         { /* errorId=6 */ }
  catch (CaptchaSonicException e)        { /* other errors */ }

SDK tự động thử lại khi gặp UNAVAILABLE, RESOURCE_EXHAUSTED, DEADLINE_EXCEEDED, với thời gian chờ tăng dần theo cấp số nhân.