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.