Skip to content
CaptchaSonic

Node.js SDK

Node.js और TypeScript के लिए आधिकारिक CaptchaSonic लाइब्रेरी — आधुनिक, Promise-आधारित, मल्टी-ट्रांसपोर्ट (gRPC / ConnectRPC / HTTP)।

CaptchaSonic Node.js SDK (captchasonic) बड़े पैमाने पर CAPTCHA हल करने के लिए एक आधुनिक, Promise-आधारित, TypeScript-first लाइब्रेरी है। हर मेथड एक Promise लौटाती है, पूरी टाइप परिभाषाएँ देती है, और तीन आपस में बदले जा सकने वाले ट्रांसपोर्ट पर चलती है — नेटिव gRPC (सबसे तेज़, केवल Node.js), ConnectRPC (Node.js और ब्राउज़र दोनों में काम करता है), और सादा HTTP/JSON। अस्थायी त्रुटियों पर exponential backoff के साथ अपने-आप retry होता है।

यह Node.js ≥ 18 और आधुनिक ब्राउज़र में काम करता है, और Express, Fastify, Next.js, React, Vue और Vite के साथ संगत है।


इंस्टॉलेशन

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

आवश्यकताएँ

आवश्यकताटिप्पणियाँ
Node.js≥ 18.0.0 (grpc ट्रांसपोर्ट के लिए आवश्यक)
मॉड्यूल फ़ॉर्मेटES Module — पैकेज "type": "module" के साथ आता है
ब्राउज़रfetch वाला कोई भी आधुनिक ब्राउज़र; connect या http ट्रांसपोर्ट का उपयोग करें

पैकेज केवल ESM के रूप में प्रकाशित है। ESM प्रोजेक्ट में (package.json में "type": "module", या .mjs फ़ाइल) इसे सीधे import करें:

import { CaptchaSonic } from "captchasonic";

CommonJS फ़ाइल से, इसे dynamic import() से लोड करें:

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

TIP

TypeScript का उपयोग कर रहे हैं तो tsconfig.json में "module": "NodeNext" (या "ESNext") और "moduleResolution": "NodeNext" सेट करें, ताकि बंडल की गई टाइप परिभाषाएँ सही तरह resolve हों।


प्रमाणीकरण

CaptchaSonic dashboard में API key बनाएँ और उसे constructor के पहले आर्गुमेंट के रूप में पास करें:

import { CaptchaSonic } from "captchasonic";

const solver = new CaptchaSonic("YOUR_API_KEY");

Keys को सोर्स कंट्रोल में कभी hard-code न करें। इसके बजाय key को एनवायरनमेंट से पढ़ें:

import { CaptchaSonic } from "captchasonic";

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

त्वरित शुरुआत

हर CAPTCHA प्रकार का एक समर्पित solve* हेल्पर होता है, जो टास्क सबमिट करता है और परिणाम के साथ resolve होता है। इमेज टास्क के लिए अलग पोलिंग चरण नहीं है — SDK यह आपके लिए संभालता है।

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

लौटाता है: इमेज मेथड एक ऐसा परिणाम resolve करती हैं जिसका उत्तर typedSolution के अंतर्गत होता है (जैसे typedSolution.grid.objects, चुने गए टाइल इंडेक्स); टोकन मेथड solution मैप में टोकन लौटाती हैं।

TIP

टोकन-आधारित मेथड (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, popular-captcha token) एक browser-automation टास्क सबमिट करती हैं और टोकन तैयार होने तक आंतरिक रूप से पोल करती हैं — डिफ़ॉल्ट रूप से 120 सेकंड तक।


समर्थित CAPTCHA प्रकार

सभी इमेज मेथड एक ही टाइप्ड options ऑब्जेक्ट लेती हैं। इमेज Uint8Array, Node Buffer, या स्ट्रिंग फ़ाइल पाथ हो सकती है (फ़ाइल पाथ केवल Node.js में)।

reCAPTCHA v2 (इमेज)

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-शैली इमेज)

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

लौटाता है: grid/click प्रकार typedSolution.grid.objects (या typedSolution.click) में आते हैं; slide typedSolution.slide.x लौटाता है।

स्वीकृत type उपनाम:

मानकउपनाम
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 / इमेज-से-टेक्स्ट

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]
विकल्पप्रकारटिप्पणियाँ
module"common" | "mtcaptcha" | "bls" | "morocco"डिफ़ॉल्ट "common"
numericbooleanकेवल अंक ("bls" के लिए स्वतः सेट)
caseSensitivebooleanअक्षरों का केस सुरक्षित रखें
minLength / maxLengthnumberलंबाई सीमाएँ

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

लौटाता है: click typedSolution.click में आता है; whirl/slide typedSolution.slide.x लौटाते हैं।

type स्वीकार करता है "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] });

लौटाता है: grid typedSolution.grid.objects में आता है; slide typedSolution.slide.x लौटाता है।

type स्वीकार करता है "grid"/"binance_grid" और "slide"/"binance_slide"।

AWS WAF

solveAwsWaf positional आर्गुमेंट लेता है। question "type:category:target" के रूप में फ़ॉर्मेट होता है।

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

लौटाता है: चुने गए टाइल इंडेक्स typedSolution.grid.objects में।

Slide इमेज (लोकल, AI नहीं)

Contour detection से स्लाइड ऑफ़सेट स्थानीय रूप से पहचाना जाता है। एक संयुक्त इमेज, या [background, piece] स्वीकार करता है।

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

लौटाता है: typedSolution.slide.x पर पिक्सल में स्लाइड ऑफ़सेट।

टोकन मेथड (browser automation)

ये टास्क सबमिट करते हैं और टोकन मिलने तक आंतरिक रूप से पोल करते हैं (डिफ़ॉल्ट रूप से पोलिंग टाइमआउट, 120 सेकंड तक)।

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

लौटाता है: रिस्पॉन्स के solution मैप में टोकन (captcha के अनुसार, जैसे result.solution.token या result.solution.gRecaptchaResponse)।


TypeScript उपयोग

SDK हर options ऑब्जेक्ट और रिस्पॉन्स के लिए टाइप्स export करता है। उन्हें import type से import करें।

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

Exported टाइप्स

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।


Proxy समर्थन

टोकन / browser-automation मेथड http://user:pass@host:port फ़ॉर्मेट में वैकल्पिक proxy स्ट्रिंग स्वीकार करती हैं:

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

WARNING

solveCloudflare को हमेशा proxy चाहिए — उस मेथड के लिए proxy फ़ील्ड अनिवार्य है। अन्य टोकन मेथड proxy छोड़ने पर proxyless चलती हैं।

Enterprise hCaptcha के लिए आप solvePopularCaptchaToken को metadata (rqdata, rqtoken, fingerprint) भी पास कर सकते हैं।


कॉन्फ़िगरेशन

Constructor के दूसरे आर्गुमेंट के रूप में एक options ऑब्जेक्ट पास करें। केवल नीचे दिए विकल्प समर्थित हैं।

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)
});
विकल्पप्रकारडिफ़ॉल्टविवरण
transport"grpc" | "connect" | "http""grpc"वायर प्रोटोकॉल (नीचे की तालिका देखें)
timeout / timeoutMsnumberप्रति कॉल 30000अनुरोध टाइमआउट; timeout पोलिंग प्रतीक्षा की सीमा भी तय करता है
pollingIntervalnumber2000टोकन टास्क कितनी बार पोल किए जाते हैं
url / baseUrlstringट्रांसपोर्ट के अनुसारAPI endpoint को ओवरराइड करें

ट्रांसपोर्ट

ट्रांसपोर्टवातावरणप्रोटोकॉल
grpcकेवल Node.jsHTTP/2 पर gRPC बाइनरी — सबसे कम विलंब, इमेज कच्चे बाइनरी में भेजता है
connectNode.js और ब्राउज़रfetch पर ConnectRPC
httpNode.js और ब्राउज़रfetch पर सादा REST/JSON

TIP

ब्राउज़र में connect (अनुशंसित) या http उपयोग करें। नेटिव gRPC को Node.js चाहिए। connect/http के साथ इमेज भेजने से पहले स्वतः base64 में एन्कोड होती हैं; grpc के साथ वे बिना किसी ओवरहेड के कच्चे बाइनरी में भेजी जाती हैं।


एरर हैंडलिंग

सभी API-स्तर की विफलताएँ SonicError फेंकती हैं, जो बिल्ट-इन Error को extend करती है। इसमें एक संख्यात्मक errorId होता है और name मिलते-जुलते एरर नाम पर सेट होता है।

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

अस्थायी gRPC त्रुटियों पर exponential backoff के साथ अपने-आप retry होता है (अधिकतम 3 प्रयास), इसलिए आमतौर पर आपको ऊपर के SonicError मामलों को ही संभालना होता है।


खाता सहायक

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

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

यदि आपको सबमिशन और पोलिंग पर सीधा नियंत्रण चाहिए, तो निम्न-स्तर के टास्क मेथड उपलब्ध हैं:

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

समस्या-निवारण

require is not defined / Cannot use import statement outside a module — पैकेज केवल ESM है। ESM प्रोजेक्ट में import उपयोग करें, या CommonJS से await import("captchasonic")। देखें इंस्टॉलेशन।

grpc ट्रांसपोर्ट ब्राउज़र में विफल — नेटिव gRPC केवल Node.js में है। transport: "connect" या transport: "http" पर स्विच करें।

हर कॉल पर InvalidApiKeyError — पुष्टि करें कि key constructor के पहले आर्गुमेंट के रूप में पास हो रही है और गलती से undefined नहीं है (जैसे एनवायरनमेंट वेरिएबल गायब होना)।

टोकन मेथड टाइमआउट — टोकन टास्क timeout ms तक पोल करते हैं (डिफ़ॉल्ट 120000)। timeout बढ़ाएँ और जाँचें कि websiteURL / websiteKey लक्ष्य पेज से मेल खाते हैं। Cloudflare के लिए वैध proxy आवश्यक है।

फ़ाइल-पाथ इमेज लोड नहीं होतीं — स्ट्रिंग फ़ाइल पाथ सिंक्रोनस पढ़े जाते हैं और केवल Node.js में हैं; ब्राउज़र में इसके बजाय Uint8Array पास करें।


संसाधन