Skip to content
CaptchaSonic

Node.js SDK

Node.js ve TypeScript için resmi CaptchaSonic kütüphanesi — modern, Promise tabanlı, çoklu taşıma (gRPC / ConnectRPC / HTTP).

CaptchaSonic Node.js SDK'sı (captchasonic), CAPTCHA'ları büyük ölçekte çözmek için modern, Promise tabanlı ve TypeScript öncelikli bir kütüphanedir. Her metot bir Promise döndürür, tam tip tanımları içerir ve birbiriyle değiştirilebilir üç taşıma üzerinden çalışır: yerel gRPC (en hızlı, yalnızca Node.js), ConnectRPC (Node.js ve tarayıcılarda çalışır) ve düz HTTP/JSON. Geçici hatalar üssel geri çekilmeyle (exponential backoff) otomatik olarak yeniden denenir.

Node.js ≥ 18 ve modern tarayıcılarda çalışır; Express, Fastify, Next.js, React, Vue ve Vite ile uyumludur.


Kurulum

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

Gereksinimler

GereksinimNotlar
Node.js≥ 18.0.0 (grpc taşıması için gerekli)
Modül biçimiES Module — paket "type": "module" ile yayımlanır
Tarayıcıfetch destekleyen her modern tarayıcı; connect veya http taşımasını kullanın

Paket yalnızca ESM olarak yayımlanır. Bir ESM projesinde (package.json içinde "type": "module" ya da bir .mjs dosyası) doğrudan içe aktarın:

import { CaptchaSonic } from "captchasonic";

CommonJS dosyasından ise dinamik import() ile yükleyin:

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

TIP

TypeScript kullanıyorsanız, paketle gelen tip tanımlarının doğru çözümlenmesi için tsconfig.json içinde "module": "NodeNext" (veya "ESNext") ve "moduleResolution": "NodeNext" ayarlayın.


Kimlik Doğrulama

CaptchaSonic panelinden bir API anahtarı oluşturun ve bunu kurucunun ilk argümanı olarak geçin:

import { CaptchaSonic } from "captchasonic";

const solver = new CaptchaSonic("YOUR_API_KEY");

Anahtarları kaynak kontrolüne asla sabit kodlamayın. Anahtarı bunun yerine ortamdan okuyun:

import { CaptchaSonic } from "captchasonic";

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

Hızlı Başlangıç

Her CAPTCHA türünün, görevi gönderen ve sonuçla çözülen özel bir solve* yardımcısı vardır. Görsel görevleri için ayrı bir sorgulama adımı yoktur — SDK bunu sizin için yönetir.

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

Dönüş: görsel metotlar, yanıtı typedSolution altında bulunan bir sonuç döndürür (ör. typedSolution.grid.objects, seçilen kare indeksleri); token metotları ise token'ı solution haritasında döndürür.

TIP

Token tabanlı metotlar (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, popular-captcha token) bir tarayıcı otomasyon görevi gönderir ve token hazır olana kadar dahili olarak sorgular — varsayılan olarak 120 saniyeye kadar.


Desteklenen CAPTCHA Türleri

Tüm görsel metotlar tek bir tipli seçenek nesnesi alır. Görseller Uint8Array, Node Buffer veya metin olarak dosya yolu olabilir (dosya yolları yalnızca Node.js'te geçerlidir).

reCAPTCHA v2 (görsel)

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 (hCaptcha benzeri görsel)

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" });

Dönüş: grid/click türleri typedSolution.grid.objects (veya typedSolution.click) alanına düşer; slide typedSolution.slide.x döndürür.

Kabul edilen type takma adları:

KanonikTakma adlar
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 / görselden metne

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]
SeçenekTürNotlar
module"common" | "mtcaptcha" | "bls" | "morocco"Varsayılan "common"
numericbooleanYalnızca rakamlar ("bls" için otomatik ayarlanır)
caseSensitivebooleanHarf büyüklüğünü koru
minLength / maxLengthnumberUzunluk sınırları

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

Dönüş: click sonucu typedSolution.click alanına düşer; whirl/slide typedSolution.slide.x döndürür.

type değeri "click"/"tiktok_click", "whirl"/"tiktok_whirl", "slide"/"tiktok_slide" kabul eder.

Binance

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

Dönüş: grid sonucu typedSolution.grid.objects alanına düşer; slide typedSolution.slide.x döndürür.

type değeri "grid"/"binance_grid" ve "slide"/"binance_slide" kabul eder.

AWS WAF

solveAwsWaf konumsal argümanlar alır. question "type:category:target" biçiminde yazılır.

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

Dönüş: seçilen kare indeksleri typedSolution.grid.objects içinde.

Slide görseli (yerel, yapay zekâsız)

Kontur tespiti kullanarak kaydırma ofsetini yerel olarak algılar. Tek birleşik bir görsel veya [background, piece] kabul eder.

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

Dönüş: kaydırma ofseti piksel cinsinden typedSolution.slide.x içinde.

Token metotları (tarayıcı otomasyonu)

Bunlar bir görev gönderir ve token dönene kadar dahili olarak sorgular (varsayılan sorgulama zaman aşımı 120 sn'ye kadar).

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

Dönüş: token, yanıtın solution haritasında yer alır (CAPTCHA'ya göre örneğin result.solution.token veya result.solution.gRecaptchaResponse).


TypeScript Kullanımı

SDK, her seçenek nesnesi ve yanıt için tipleri dışa aktarır. import type ile içe aktarın.

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);

Dışa aktarılan tipler

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, Uint8Array | Buffer | string tipindedir.


Proxy Desteği

Token / tarayıcı otomasyonu metotları, http://user:pass@host:port biçiminde isteğe bağlı bir proxy metni kabul eder:

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

WARNING

solveCloudflare her zaman proxy gerektirir — bu metot için proxy alanı zorunludur. Diğer token metotları proxy atlandığında proxysiz çalışır.

Kurumsal hCaptcha için solvePopularCaptchaToken metoduna metadata (rqdata, rqtoken, fingerprint) de geçebilirsiniz.


Yapılandırma

Kurucunun ikinci argümanı olarak bir seçenek nesnesi geçin. Yalnızca aşağıdaki seçenekler desteklenir.

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)
});
SeçenekTürVarsayılanAçıklama
transport"grpc" | "connect" | "http""grpc"Tel protokolü (aşağıdaki tabloya bakın)
timeout / timeoutMsnumberÇağrı başına 30000İstek zaman aşımı; timeout sorgu bekleme süresini de sınırlar
pollingIntervalnumber2000Token görevlerinin ne sıklıkla sorgulanacağı
url / baseUrlstringtaşımaya göreAPI uç noktasını geçersiz kıl

Taşımalar

TaşımaOrtamlarProtokol
grpcYalnızca Node.jsHTTP/2 üzerinden gRPC ikili — en düşük gecikme, görselleri ham ikili olarak gönderir
connectNode.js ve tarayıcılarfetch üzerinden ConnectRPC
httpNode.js ve tarayıcılarfetch üzerinden düz REST/JSON

TIP

Tarayıcıda connect (önerilen) veya http kullanın. Yerel gRPC Node.js gerektirir. connect/http ile görseller gönderilmeden önce otomatik olarak base64'e kodlanır; grpc ile ise sıfır ek yükle ham ikili olarak gönderilir.


Hata Yönetimi

API düzeyindeki tüm hatalar, yerleşik Error sınıfını genişleten bir SonicError fırlatır. Sayısal bir errorId taşır ve name alanını eşleşen hata adına ayarlar.

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

Geçici gRPC hataları üssel geri çekilmeyle otomatik olarak yeniden denenir (en fazla 3 deneme); bu yüzden genellikle yalnızca yukarıdaki SonicError durumlarını ele almanız yeterlidir.


Hesap Yardımcıları

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

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

Gönderim ve sorgulama üzerinde doğrudan kontrole ihtiyacınız varsa düşük seviyeli görev metotları da mevcuttur:

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

Sorun Giderme

require is not defined / Cannot use import statement outside a module — paket yalnızca ESM'dir. ESM projesinde import kullanın veya CommonJS'ten await import("captchasonic") çağırın. Bkz. Kurulum.

grpc taşıması tarayıcıda başarısız oluyor — yerel gRPC yalnızca Node.js'tedir. transport: "connect" veya transport: "http" seçeneğine geçin.

Her çağrıda InvalidApiKeyError — anahtarın kurucunun ilk argümanı olarak geçildiğini ve yanlışlıkla undefined olmadığını doğrulayın (ör. eksik bir ortam değişkeni).

Token metodu zaman aşımına uğruyor — token görevleri en fazla timeout ms (varsayılan 120000) sorgulanır. timeout değerini artırın ve websiteURL / websiteKey değerlerinin hedef sayfayla eşleştiğini doğrulayın. Cloudflare için geçerli bir proxy gereklidir.

Dosya yolu olarak verilen görseller yüklenmiyor — metin olarak dosya yolları eşzamanlı okunur ve yalnızca Node.js'te çalışır; tarayıcıda bunun yerine bir Uint8Array geçin.


Kaynaklar