Java SDK
CaptchaSonic 공식 Java SDK — gRPC 바이너리 전송, 스레드 안전, CompletableFuture 비동기.
CaptchaSonic CAPTCHA solving API용 공식 Java SDK입니다.
전송 방식
grpc-netty-shaded를 통해 네이티브 gRPC를 사용합니다. 이미지는 base64 오버헤드 없이 원시 바이너리로 전송됩니다.
설치
Gradle
implementation 'com.captchasonic:captchasonic:1.0.0'
Maven
<dependency>
<groupId>com.captchasonic</groupId>
<artifactId>captchasonic</artifactId>
<version>1.0.0</version>
</dependency>
빠른 시작
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());
}
빌더 패턴
CaptchaSonicClient client = CaptchaSonicClient.builder()
.apiKey("sonic_xxx")
.host("api.captchasonic.com")
.port(443)
.timeout(Duration.ofSeconds(120))
.build();
사용자 지정 엔드포인트
var client = new CaptchaSonicClient("sonic_xxx", "api.captchasonic.com", 443, true);
클라이언트는 스레드 안전합니다. 인스턴스를 하나 만들어 재사용하세요.
이미지 솔버
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()
토큰 자동화 메서드
이 메서드들은 작업을 제출한 뒤 토큰이 반환될 때까지 폴링합니다(최대 120초).
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
블로킹 메서드마다 CompletableFuture<CreateTaskResponse>를 반환하는 Async 버전이 있습니다.
유틸리티 메서드
double balance = client.getBalance();
HealthCheckResponse health = client.healthCheck();
GetTaskResultResponse result = client.getTaskResult(taskId);
오류 처리
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 */ }
UNAVAILABLE, RESOURCE_EXHAUSTED, DEADLINE_EXCEEDED가 발생하면 지수 백오프로 재시도합니다.