Node.js-SDK
Offizielle CaptchaSonic-Bibliothek für Node.js und TypeScript — modern, Promise-basiert, mit mehreren Transporten (gRPC / ConnectRPC / HTTP).
Das CaptchaSonic-Node.js-SDK (captchasonic) ist eine moderne, Promise-basierte, TypeScript-first-Bibliothek zum Lösen von CAPTCHAs in großem Maßstab. Jede Methode gibt ein Promise zurück, bringt vollständige Typdefinitionen mit und läuft über drei austauschbare Transporte — natives gRPC (am schnellsten, nur Node.js), ConnectRPC (funktioniert in Node.js und Browsern) und einfaches HTTP/JSON. Vorübergehende Fehler werden automatisch mit exponentiellem Backoff erneut versucht.
Es funktioniert in Node.js ≥ 18 und in modernen Browsern und ist kompatibel mit Express, Fastify, Next.js, React, Vue und Vite.
Installation
npm install captchasonic
# or
yarn add captchasonic
# or
pnpm add captchasonic
Voraussetzungen
| Voraussetzung | Hinweise |
|---|---|
| Node.js | ≥ 18.0.0 (erforderlich für den grpc-Transport) |
| Modulformat | ES-Modul — das Paket wird mit "type": "module" ausgeliefert |
| Browser | Jeder moderne Browser mit fetch; verwenden Sie den Transport connect oder http |
Das Paket wird nur als ESM veröffentlicht. In einem ESM-Projekt ("type": "module" in Ihrer package.json oder eine .mjs-Datei) importieren Sie es direkt:
import { CaptchaSonic } from "captchasonic";
Aus einer CommonJS-Datei laden Sie es über einen dynamischen import():
// CommonJS (.cjs / "type": "commonjs")
const { CaptchaSonic } = await import("captchasonic");
TIP
Wenn Sie TypeScript verwenden, setzen Sie in tsconfig.json "module": "NodeNext" (oder "ESNext") und "moduleResolution": "NodeNext", damit die mitgelieferten Typdefinitionen korrekt aufgelöst werden.
Authentifizierung
Erstellen Sie einen API-Schlüssel im CaptchaSonic-Dashboard und übergeben Sie ihn als erstes Argument an den Konstruktor:
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic("YOUR_API_KEY");
Hinterlegen Sie Schlüssel niemals fest im Quellcode oder in der Versionsverwaltung. Lesen Sie den Schlüssel stattdessen aus der Umgebung:
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
Schnellstart
Jeder CAPTCHA-Typ hat eine eigene solve*-Hilfsfunktion, die den Task übermittelt und mit dem Ergebnis aufgelöst wird. Bei Bild-Tasks ist kein separater Abfrageschritt nötig — das SDK übernimmt dies für Sie.
solveRecaptchaV2TokentokenreCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).
solveRecaptchaV2Token(…)returnssolution.tokenimport { 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 fieldfrom captchasonic import CaptchaSonic
solver = CaptchaSonic("YOUR_API_KEY")
result = solver.solve_recaptcha_v2_token(
website_url="https://example.com/login",
website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
)
print(result["token"])
# 03AGdBq25SxXT... ← drop this into the g-recaptcha-response fieldRückgabe: Bildmethoden liefern ein Ergebnis, dessen Antwort unter
typedSolutionliegt (z. B.typedSolution.grid.objects, die gewählten Kachel-Indizes); Token-Methoden geben das Token in dersolution-Map zurück.
TIP
Token-basierte Methoden (Turnstile, Cloudflare, reCAPTCHA v2/v3-Token, PopularCaptcha-Token) übermitteln einen Browser-Automatisierungs-Task und fragen intern ab, bis ein Token bereitsteht — standardmäßig bis zu 120 Sekunden.
Unterstützte CAPTCHA-Typen
Alle Bildmethoden nehmen ein einziges typisiertes Optionsobjekt entgegen. Bilder können Uint8Array, Node-Buffer oder ein String-Dateipfad sein (Dateipfade gibt es nur in Node.js).
reCAPTCHA v2 (Bild)
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-artiges Bild)
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" });
Rückgabe: Grid- und Click-Typen landen in typedSolution.grid.objects (bzw. typedSolution.click); Slide liefert typedSolution.slide.x.
Akzeptierte type-Aliasse:
| Kanonisch | Aliasse |
|---|---|
| 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 / Bild-zu-Text
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]
| Option | Typ | Hinweise |
|---|---|---|
module | "common" | "mtcaptcha" | "bls" | "morocco" | Standard "common" |
numeric | boolean | Nur Ziffern (wird für "bls" automatisch gesetzt) |
caseSensitive | boolean | Groß-/Kleinschreibung beibehalten |
minLength / maxLength | number | Längengrenzen |
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
Rückgabe: click landet in typedSolution.click; whirl/slide liefern typedSolution.slide.x.
type akzeptiert "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] });
Rückgabe: grid landet in typedSolution.grid.objects; slide liefert typedSolution.slide.x.
type akzeptiert "grid"/"binance_grid" und "slide"/"binance_slide".
AWS WAF
solveAwsWaf nimmt Positionsargumente entgegen. Die question wird im Format "type:category:target" angegeben.
await solver.solveAwsWaf(tiles, "grid:vehicles:cars");
Rückgabe: die gewählten Kachel-Indizes in typedSolution.grid.objects.
Slide-Bild (lokal, ohne KI)
Ermittelt den Slide-Versatz lokal per Konturerkennung. Akzeptiert ein kombiniertes Bild oder [background, piece].
const r = await solver.solveSlideImage({ images: ["slide_bg.png", "piece.png"] });
console.log(r.typedSolution?.slide?.x); // pixel offset, e.g. 142
Rückgabe: der Slide-Versatz in Pixeln unter typedSolution.slide.x.
Token-Methoden (Browser-Automatisierung)
Diese übermitteln einen Task und fragen intern ab, bis ein Token zurückgegeben wird (bis zum Abfrage-Timeout, standardmäßig 120 s).
solveTurnstiletokenCloudflare Turnstile — Solve a Cloudflare Turnstile token challenge (async — polls until ready).
solveTurnstile(…)returnssolution.tokenawait 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 REQUIREDsolver.solve_turnstile(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_recaptcha_v2_token(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_recaptcha_v3_token(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_popular_captcha_token(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_cloudflare(website_url=..., website_key=..., proxy=...) # proxy REQUIREDRückgabe: das Token in der solution-Map der Antwort (z. B. result.solution.token oder result.solution.gRecaptchaResponse, je nach CAPTCHA).
TypeScript-Verwendung
Das SDK exportiert Typen für jedes Optionsobjekt und jede Antwort. Importieren Sie sie mit 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);
Exportierte Typen
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 ist Uint8Array | Buffer | string.
Proxy-Unterstützung
Token-/Browser-Automatisierungsmethoden akzeptieren einen optionalen proxy-String im Format http://user:pass@host:port:
await solver.solveTurnstile({
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA...",
proxy: "http://user:[email protected]:8080",
});
WARNING
solveCloudflare benötigt immer einen Proxy — das Feld proxy ist für diese Methode Pflicht. Andere Token-Methoden laufen ohne Proxy, wenn proxy weggelassen wird.
Für Enterprise-hCaptcha können Sie zusätzlich metadata (rqdata, rqtoken, fingerprint) an solvePopularCaptchaToken übergeben.
Konfiguration
Übergeben Sie ein Optionsobjekt als zweites Argument des Konstruktors. Es werden nur die unten genannten Optionen unterstützt.
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)
});
| Option | Typ | Standard | Beschreibung |
|---|---|---|---|
transport | "grpc" | "connect" | "http" | "grpc" | Wire-Protokoll (siehe Tabelle unten) |
timeout / timeoutMs | number | 30000 pro Aufruf | Request-Timeout; timeout begrenzt auch die Wartezeit beim Abfragen |
pollingInterval | number | 2000 | Wie oft Token-Tasks abgefragt werden |
url / baseUrl | string | je Transport | Überschreibt den API-Endpunkt |
Transporte
| Transport | Umgebungen | Protokoll |
|---|---|---|
grpc | nur Node.js | gRPC-Binärprotokoll über HTTP/2 — geringste Latenz, sendet Bilder als rohe Binärdaten |
connect | Node.js und Browser | ConnectRPC über fetch |
http | Node.js und Browser | Einfaches REST/JSON über fetch |
TIP
Im Browser verwenden Sie connect (empfohlen) oder http. Natives gRPC setzt Node.js voraus. Bei connect/http werden Bilder vor dem Senden automatisch in Base64 kodiert; bei grpc werden sie als rohe Binärdaten ohne Overhead gesendet.
Fehlerbehandlung
Alle API-seitigen Fehler werfen eine SonicError, die von dem eingebauten Error erbt. Sie trägt einen numerischen errorId und setzt name auf den passenden Fehlernamen.
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
}
}
| id | Python exception | Node errorName | Meaning | Action |
|---|---|---|---|---|
0 | SonicError | SonicError | Base class for every SDK error — catches anything below. | Inspect `error.errorId` (Node) / `err.error_id` (Python) and branch. |
1 | InvalidApiKeyError | InvalidApiKeyError | API key is missing, malformed, or revoked. | Verify the key in your dashboard. |
2 | InsufficientBalanceError | InsufficientBalanceError | Account balance can't cover the task. | Add funds. |
3 | DailyLimitExceededError | DailyLimitExceededError | Daily quota exhausted. | Wait for the daily reset or upgrade your plan. |
4 | MinuteLimitExceededError | MinuteLimitExceededError | Per-minute rate limit hit. | Slow down requests / add exponential backoff. |
5 | QuotaExceededError | QuotaExceededError | Plan quota exhausted. | Upgrade your plan. |
6 | PlanExpiredError | PlanExpiredError | Subscription 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
Vorübergehende gRPC-Fehler werden automatisch mit exponentiellem Backoff erneut versucht (bis zu 3 Versuche), sodass Sie in der Regel nur die oben genannten SonicError-Fälle behandeln müssen.
Konto-Hilfsfunktionen
const balance = await solver.getBalance(); // → number (USD)
const health = await solver.healthCheck(); // → { healthy: boolean, version: string }
Low-Level-Task-Methoden stehen zur Verfügung, wenn Sie die Übermittlung und Abfrage direkt steuern möchten:
const created = await solver.createTask(task); // submit a Partial<Task>
const result = await solver.getTaskResult(taskId); // poll for a result
Fehlersuche
require is not defined / Cannot use import statement outside a module — das Paket ist nur als ESM verfügbar. Verwenden Sie import in einem ESM-Projekt oder await import("captchasonic") aus CommonJS. Siehe Installation.
grpc-Transport schlägt im Browser fehl — natives gRPC funktioniert nur in Node.js. Wechseln Sie auf transport: "connect" oder transport: "http".
InvalidApiKeyError bei jedem Aufruf — prüfen Sie, ob der Schlüssel als erstes Konstruktorargument übergeben wird und nicht versehentlich undefined ist (z. B. wegen einer fehlenden Umgebungsvariable).
Token-Methode läuft in Timeout — Token-Tasks fragen bis zu timeout ms ab (Standard 120000). Erhöhen Sie timeout und prüfen Sie, ob websiteURL / websiteKey zur Zielseite passen. Für Cloudflare ist ein gültiger proxy erforderlich.
Bilder aus Dateipfaden werden nicht geladen — String-Dateipfade werden synchron gelesen und sind nur in Node.js verfügbar; im Browser übergeben Sie stattdessen ein Uint8Array.