Skip to content
CaptchaSonic

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가 발생하면 지수 백오프로 재시도합니다.