Skip to content
CaptchaSonic

SDK Node.js

Pustaka resmi CaptchaSonic untuk Node.js dan TypeScript — modern, berbasis Promise, multi-transport (gRPC / ConnectRPC / HTTP).

SDK Node.js CaptchaSonic (captchasonic) adalah pustaka modern, berbasis Promise, dan mengutamakan TypeScript untuk menyelesaikan CAPTCHA dalam skala besar. Setiap metode mengembalikan Promise, menyertakan definisi tipe lengkap, dan berjalan di atas tiga transport yang dapat dipertukarkan — gRPC native (tercepat, hanya Node.js), ConnectRPC (berjalan di Node.js dan browser), dan HTTP/JSON biasa. Error sementara dicoba ulang secara otomatis dengan exponential backoff.

SDK ini berjalan di Node.js ≥ 18 dan browser modern, serta kompatibel dengan Express, Fastify, Next.js, React, Vue, dan Vite.


Instalasi

npm install captchasonic
# or
yarn add captchasonic
# or
pnpm add captchasonic

Persyaratan

PersyaratanCatatan
Node.js≥ 18.0.0 (wajib untuk transport grpc)
Format modulES Module — paket ini menyertakan "type": "module"
BrowserBrowser modern apa pun dengan fetch; gunakan transport connect atau http

Paket ini dipublikasikan hanya ESM. Dalam proyek ESM ("type": "module" di package.json, atau file .mjs), impor langsung:

import { CaptchaSonic } from "captchasonic";

Dari file CommonJS, muat dengan import() dinamis:

// CommonJS (.cjs / "type": "commonjs")
const { CaptchaSonic } = await import("captchasonic");

TIP

Jika Anda menggunakan TypeScript, atur "module": "NodeNext" (atau "ESNext") dan "moduleResolution": "NodeNext" di tsconfig.json agar definisi tipe bawaan dapat di-resolve dengan benar.


Autentikasi

Buat API key di dashboard CaptchaSonic lalu berikan sebagai argumen pertama ke constructor:

import { CaptchaSonic } from "captchasonic";

const solver = new CaptchaSonic("YOUR_API_KEY");

Jangan pernah menulis key langsung di kode sumber (source control). Baca key dari environment:

import { CaptchaSonic } from "captchasonic";

const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);

Mulai Cepat

Setiap jenis captcha memiliki helper solve* khusus yang mengirim task dan mengembalikan hasilnya. Tidak ada langkah polling terpisah untuk task gambar — SDK menanganinya untuk Anda.

solveRecaptchaV2Tokentoken
Verified v2.0.0· 2026-05-28

reCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).

signaturesolveRecaptchaV2Token(…)returnssolution.token
import { CaptchaSonic } from "captchasonic";

const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);

const result = await solver.solveRecaptchaV2Token({
  websiteURL: "https://example.com/login",
  websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});

console.log(result.solution.gRecaptchaResponse);
// 03AGdBq25SxXT...  ← drop into the g-recaptcha-response field

Mengembalikan: metode gambar menghasilkan hasil yang jawabannya berada di typedSolution (mis. typedSolution.grid.objects, indeks tile yang dipilih); metode token mengembalikan token di dalam map solution.

TIP

Metode berbasis token (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, popular-captcha token) mengirim task otomasi browser dan melakukan polling secara internal hingga token siap — secara default hingga 120 detik.


Jenis CAPTCHA yang Didukung

Semua metode gambar menerima satu objek opsi bertipe. Gambar dapat berupa Uint8Array, Buffer Node, atau path file berupa string (path file hanya untuk Node.js).

reCAPTCHA v2 (gambar)

await solver.solveRecaptchaV2({
  images: tiles,                 // typically 9 tiles for a 3×3 grid
  question: "traffic lights",    // plain text, or a Google class code like "/m/015qff"
});
// → result.typedSolution.grid.objects  (number[] — selected tile indices)

PopularCaptcha (gambar gaya hCaptcha)

await solver.solvePopularCaptcha({
  images: tiles,                 // 1–64 tiles
  question: "Click each image with a cat",
  questionType: "objectClassify", // "objectClassify" | "grid" | "objectClick" | "objectDrag"
  examples,                      // optional reference images for objectClick
  websiteURL: "https://example.com",
});
// objectClassify/grid → typedSolution.grid.objects
// objectClick        → typedSolution.click
// objectDrag         → typedSolution.drag

GeeTest

// nine-grid (question + images required)
await solver.solveGeetest({ type: "nine", question: "Select all bicycles", images: tiles });

// click / icon (question + images required)
await solver.solveGeetest({ type: "click", question: "the bear", images: tiles });

// slide puzzle (piece + background)
await solver.solveGeetest({ type: "slide", images: [piece], examples: [background] });

// swap puzzles
await solver.solveGeetest({ type: "match" });
await solver.solveGeetest({ type: "winlinze" });

Mengembalikan: tipe grid/click masuk ke typedSolution.grid.objects (atau typedSolution.click); slide mengembalikan typedSolution.slide.x.

Alias type yang diterima:

KanonikAlias
nine-grid"nine", "geetest_nine", "9"
click / icon"click", "geetest_click", "icon"
slide"slide", "geetest_slide"
match"match", "geetest_match"
winlinze"winlinze", "geetest_winlinze"

OCR / gambar-ke-teks

await solver.solveOcr({ images: [img] });                                  // general OCR
await solver.solveOcr({ images: [img], module: "mtcaptcha", maxLength: 4 });
await solver.solveOcr({ images: imgs, module: "bls", numeric: true, maxLength: 3 });
// → result.typedSolution.text.texts[0]
OpsiTipeCatatan
module"common" | "mtcaptcha" | "bls" | "morocco"Default "common"
numericbooleanHanya digit (otomatis aktif untuk "bls")
caseSensitivebooleanPertahankan huruf besar/kecil
minLength / maxLengthnumberBatas panjang

TikTok

await solver.solveTikTok({ type: "click", question: "Select the shape", images });
await solver.solveTikTok({ type: "whirl", question: "Rotate to match", images, examples }); // examples required
await solver.solveTikTok({ type: "slide", question: "Slide to fit", images, examples });    // examples required

Mengembalikan: click masuk ke typedSolution.click; whirl/slide mengembalikan typedSolution.slide.x.

type menerima "click"/"tiktok_click", "whirl"/"tiktok_whirl", "slide"/"tiktok_slide".

Binance

await solver.solveBinance({ type: "grid", question: "Select the bicycle", images });
await solver.solveBinance({ type: "slide", images: [puzzle], examples: [background] });

Mengembalikan: grid masuk ke typedSolution.grid.objects; slide mengembalikan typedSolution.slide.x.

type menerima "grid"/"binance_grid" dan "slide"/"binance_slide".

AWS WAF

solveAwsWaf menerima argumen posisional. question diformat sebagai "type:category:target".

await solver.solveAwsWaf(tiles, "grid:vehicles:cars");

Mengembalikan: indeks tile yang dipilih di typedSolution.grid.objects.

Gambar slide (lokal, tanpa AI)

Mendeteksi offset slide secara lokal menggunakan deteksi kontur. Menerima satu gambar gabungan, atau [background, piece].

const r = await solver.solveSlideImage({ images: ["slide_bg.png", "piece.png"] });
console.log(r.typedSolution?.slide?.x); // pixel offset, e.g. 142

Mengembalikan: offset slide dalam piksel di typedSolution.slide.x.

Metode token (otomasi browser)

Metode ini mengirim task dan melakukan polling secara internal hingga token dikembalikan (hingga batas waktu polling, secara default 120 detik).

solveTurnstiletoken
Verified v2.0.0· 2026-05-28

Cloudflare Turnstile — Solve a Cloudflare Turnstile token challenge (async — polls until ready).

signaturesolveTurnstile(…)returnssolution.token
await solver.solveTurnstile({ websiteURL, websiteKey, proxy });          // proxy optional
await solver.solveRecaptchaV2Token({ websiteURL, websiteKey, proxy });   // proxy optional
await solver.solveRecaptchaV3Token({ websiteURL, websiteKey, proxy });   // proxy optional
await solver.solvePopularCaptchaToken({ websiteURL, websiteKey, proxy, metadata }); // proxy optional
await solver.solveCloudflare({ websiteURL, websiteKey, proxy });         // proxy REQUIRED

Mengembalikan: token ada di map solution dari respons (misalnya result.solution.token atau result.solution.gRecaptchaResponse, tergantung captcha).


Penggunaan TypeScript

SDK mengekspor tipe untuk setiap objek opsi dan respons. Impor dengan import type.

import { CaptchaSonic } from "captchasonic";
import type { SolveGeetestOptions, GetTaskResultResponse } from "captchasonic";

const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY!);

const opts: SolveGeetestOptions = {
  type: "nine",
  question: "Select all bicycles",
  images: tiles,
};

const result = await solver.solveGeetest(opts);
console.log(result.typedSolution?.grid?.objects);

Tipe yang diekspor

import type {
  CaptchaSonicOptions,
  ImageInput,
  SolvePopularCaptchaOptions,
  SolveRecaptchaV2Options,
  SolveGeetestOptions,
  SolveOcrOptions,
  SolveTikTokOptions,
  SolveBinanceOptions,
  SolveTurnstileOptions,
  SolvePopularCaptchaTokenOptions,
  SolveRecaptchaV2TokenOptions,
  SolveRecaptchaV3TokenOptions,
  SolveCloudflareOptions,
  SolveSlideImageOptions,
  GeetestSubtype,
  TikTokSubtype,
  BinanceSubtype,
  Task,
  CreateTaskResponse,
  GetTaskResultResponse,
} from "captchasonic";

ImageInput adalah Uint8Array | Buffer | string.


Dukungan Proxy

Metode token / otomasi browser menerima string proxy opsional dengan format http://user:pass@host:port:

await solver.solveTurnstile({
  websiteURL: "https://example.com",
  websiteKey: "0x4AAAAAAA...",
  proxy: "http://user:[email protected]:8080",
});

WARNING

solveCloudflare selalu memerlukan proxy — field proxy wajib untuk metode tersebut. Metode token lainnya berjalan tanpa proxy jika proxy dihilangkan.

Untuk hCaptcha enterprise, Anda juga dapat meneruskan metadata (rqdata, rqtoken, fingerprint) ke solvePopularCaptchaToken.


Konfigurasi

Berikan objek opsi sebagai argumen kedua constructor. Hanya opsi di bawah ini yang didukung.

const solver = new CaptchaSonic("YOUR_API_KEY", {
  transport: "connect",   // "grpc" (default) | "connect" | "http"
  timeout: 180_000,       // max poll wait in ms (alias: timeoutMs); per-call default 30000
  pollingInterval: 5_000, // polling frequency in ms (default 2000)
  baseUrl: "https://api.captchasonic.com", // override endpoint (alias: url)
});
OpsiTipeDefaultDeskripsi
transport"grpc" | "connect" | "http""grpc"Protokol kabel (lihat tabel di bawah)
timeout / timeoutMsnumber30000 per panggilanBatas waktu permintaan; timeout juga membatasi waktu tunggu polling
pollingIntervalnumber2000Seberapa sering task token di-polling
url / baseUrlstringper transportMengganti endpoint API

Transport

TransportLingkunganProtokol
grpcHanya Node.jsgRPC biner di atas HTTP/2 — latensi terendah, mengirim gambar sebagai biner mentah
connectNode.js dan browserConnectRPC di atas fetch
httpNode.js dan browserREST/JSON biasa di atas fetch

TIP

Di browser gunakan connect (direkomendasikan) atau http. gRPC native memerlukan Node.js. Dengan connect/http, gambar otomatis di-encode ke base64 sebelum dikirim; dengan grpc gambar dikirim sebagai biner mentah tanpa overhead.


Penanganan Error

Semua kegagalan tingkat API melempar SonicError, yang merupakan turunan dari Error bawaan. Error ini membawa errorId numerik dan mengatur name sesuai nama error yang sesuai.

import { CaptchaSonic, SonicError } from "captchasonic";

try {
  const result = await solver.solveGeetest({ type: "nine", question: "bicycles", images });
} catch (err) {
  if (err instanceof SonicError) {
    console.error(err.errorId); // 1–6
    console.error(err.name);    // e.g. "InvalidApiKeyError"
    console.error(err.message);
  } else {
    throw err; // network / unexpected
  }
}
errors7 canonical `errorId` codes
idPython exceptionNode errorNameMeaningAction
0SonicErrorSonicErrorBase class for every SDK error — catches anything below.Inspect `error.errorId` (Node) / `err.error_id` (Python) and branch.
1InvalidApiKeyErrorInvalidApiKeyErrorAPI key is missing, malformed, or revoked.Verify the key in your dashboard.
2InsufficientBalanceErrorInsufficientBalanceErrorAccount balance can't cover the task.Add funds.
3DailyLimitExceededErrorDailyLimitExceededErrorDaily quota exhausted.Wait for the daily reset or upgrade your plan.
4MinuteLimitExceededErrorMinuteLimitExceededErrorPer-minute rate limit hit.Slow down requests / add exponential backoff.
5QuotaExceededErrorQuotaExceededErrorPlan quota exhausted.Upgrade your plan.
6PlanExpiredErrorPlanExpiredErrorSubscription has expired.Renew your subscription.

Every concrete row inherits from SonicError — catch it once to handle all SDK failures, or branch on errorId / exception subclass for granular control. Transient gRPC errors are retried automatically with exponential backoff (up to 3 attempts).

TIP

Error gRPC sementara dicoba ulang secara otomatis dengan exponential backoff (hingga 3 percobaan), sehingga biasanya Anda hanya perlu menangani kasus SonicError di atas.


Helper Akun

const balance = await solver.getBalance(); // → number (USD)

const health = await solver.healthCheck(); // → { healthy: boolean, version: string }

Metode task tingkat rendah tersedia jika Anda memerlukan kontrol langsung atas pengiriman dan polling:

const created = await solver.createTask(task);        // submit a Partial<Task>
const result  = await solver.getTaskResult(taskId);   // poll for a result

Pemecahan Masalah

require is not defined / Cannot use import statement outside a module — paket ini hanya ESM. Gunakan import di proyek ESM, atau await import("captchasonic") dari CommonJS. Lihat Instalasi.

Transport grpc gagal di browser — gRPC native hanya untuk Node.js. Ganti ke transport: "connect" atau transport: "http".

InvalidApiKeyError pada setiap panggilan — pastikan key diberikan sebagai argumen pertama constructor dan bukan undefined secara tidak sengaja (mis. variabel env yang belum diatur).

Metode token kehabisan waktu — task token di-polling hingga timeout ms (default 120000). Tingkatkan timeout dan pastikan websiteURL / websiteKey sesuai dengan halaman target. Untuk Cloudflare, proxy yang valid wajib diisi.

Gambar dengan path file tidak termuat — path file berupa string dibaca secara sinkron dan hanya untuk Node.js; di browser berikan Uint8Array sebagai gantinya.


Sumber Daya