SDK Node.js
Bibliothèque officielle CaptchaSonic pour Node.js et TypeScript — moderne, basée sur les Promises, multi-transport (gRPC / ConnectRPC / HTTP).
Le SDK Node.js de CaptchaSonic (captchasonic) est une bibliothèque moderne, basée sur les Promises et orientée TypeScript, pour résoudre des CAPTCHA à grande échelle. Chaque méthode renvoie une Promise, fournit des définitions de types complètes et fonctionne avec trois transports interchangeables : gRPC natif (le plus rapide, Node.js uniquement), ConnectRPC (fonctionne dans Node.js et les navigateurs) et HTTP/JSON simple. Les erreurs transitoires sont relancées automatiquement avec un backoff exponentiel.
Il fonctionne avec Node.js ≥ 18 et les navigateurs modernes, et est compatible avec Express, Fastify, Next.js, React, Vue et Vite.
Installation
npm install captchasonic
# or
yarn add captchasonic
# or
pnpm add captchasonic
Prérequis
| Prérequis | Remarques |
|---|---|
| Node.js | ≥ 18.0.0 (requis pour le transport grpc) |
| Format de module | ES Module — le package embarque "type": "module" |
| Navigateur | Tout navigateur moderne disposant de fetch ; utilisez le transport connect ou http |
Le package est publié uniquement en ESM. Dans un projet ESM ("type": "module" dans votre package.json, ou un fichier .mjs), importez-le directement :
import { CaptchaSonic } from "captchasonic";
Depuis un fichier CommonJS, chargez-le avec un import() dynamique :
// CommonJS (.cjs / "type": "commonjs")
const { CaptchaSonic } = await import("captchasonic");
TIP
Si vous utilisez TypeScript, définissez "module": "NodeNext" (ou "ESNext") et "moduleResolution": "NodeNext" dans tsconfig.json pour que les définitions de types incluses se résolvent correctement.
Authentification
Créez une clé API dans le tableau de bord CaptchaSonic et passez-la en premier argument du constructeur :
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic("YOUR_API_KEY");
Ne codez jamais les clés en dur dans le contrôle de version. Lisez plutôt la clé depuis l'environnement :
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
Démarrage rapide
Chaque type de CAPTCHA dispose d'une fonction solve* dédiée qui soumet la tâche et se résout avec le résultat. Il n'y a pas d'étape d'interrogation séparée pour les tâches d'image : le SDK s'en charge.
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 fieldRetourne : les méthodes d'image se résolvent avec un résultat dont la réponse se trouve sous
typedSolution(par exempletypedSolution.grid.objects, les indices des tuiles sélectionnées) ; les méthodes de jeton renvoient le jeton dans la mapsolution.
TIP
Les méthodes à base de jeton (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, jeton popular-captcha) soumettent une tâche d'automatisation de navigateur et interrogent le résultat en interne jusqu'à ce qu'un jeton soit prêt — par défaut pendant 120 secondes au maximum.
Types de CAPTCHA pris en charge
Toutes les méthodes d'image acceptent un unique objet d'options typé. Les images peuvent être des Uint8Array, des Buffer Node ou un chemin de fichier sous forme de chaîne (les chemins de fichiers ne sont disponibles que dans Node.js).
reCAPTCHA v2 (image)
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 (image de style 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" });
Retourne : les types grid/click arrivent dans typedSolution.grid.objects (ou typedSolution.click) ; slide renvoie typedSolution.slide.x.
Alias de type acceptés :
| Forme canonique | Alias |
|---|---|
| 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 / image vers texte
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 | Type | Remarques |
|---|---|---|
module | "common" | "mtcaptcha" | "bls" | "morocco" | Par défaut "common" |
numeric | boolean | Chiffres uniquement (réglé automatiquement pour "bls") |
caseSensitive | boolean | Conserve la casse des lettres |
minLength / maxLength | number | Bornes de longueur |
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
Retourne : click arrive dans typedSolution.click ; whirl/slide renvoient typedSolution.slide.x.
type accepte "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] });
Retourne : grid arrive dans typedSolution.grid.objects ; slide renvoie typedSolution.slide.x.
type accepte "grid"/"binance_grid" et "slide"/"binance_slide".
AWS WAF
solveAwsWaf prend des arguments positionnels. La question est formatée comme "type:category:target".
await solver.solveAwsWaf(tiles, "grid:vehicles:cars");
Retourne : les indices des tuiles sélectionnées dans typedSolution.grid.objects.
Image de glissement (locale, sans IA)
Détecte localement le décalage du curseur par détection de contours. Accepte une image combinée unique, ou [background, piece].
const r = await solver.solveSlideImage({ images: ["slide_bg.png", "piece.png"] });
console.log(r.typedSolution?.slide?.x); // pixel offset, e.g. 142
Retourne : le décalage en pixels dans typedSolution.slide.x.
Méthodes à jeton (automatisation du navigateur)
Elles soumettent une tâche et interrogent le résultat en interne jusqu'à obtenir un jeton (jusqu'au délai d'interrogation, 120 s par défaut).
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 REQUIREDRetourne : le jeton dans la map solution de la réponse (par exemple result.solution.token ou result.solution.gRecaptchaResponse, selon le CAPTCHA).
Utilisation de TypeScript
Le SDK exporte les types de chaque objet d'options et de réponse. Importez-les avec 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);
Types exportés
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 est Uint8Array | Buffer | string.
Prise en charge des proxys
Les méthodes de jeton / d'automatisation de navigateur acceptent une chaîne proxy optionnelle au format http://user:pass@host:port :
await solver.solveTurnstile({
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA...",
proxy: "http://user:[email protected]:8080",
});
WARNING
solveCloudflare exige toujours un proxy — le champ proxy est obligatoire pour cette méthode. Les autres méthodes de jeton s'exécutent sans proxy lorsque proxy est omis.
Pour le hCaptcha entreprise, vous pouvez aussi passer metadata (rqdata, rqtoken, fingerprint) à solvePopularCaptchaToken.
Configuration
Passez un objet d'options comme second argument du constructeur. Seules les options ci-dessous sont prises en charge.
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 | Type | Défaut | Description |
|---|---|---|---|
transport | "grpc" | "connect" | "http" | "grpc" | Protocole de transport (voir le tableau ci-dessous) |
timeout / timeoutMs | number | 30000 par appel | Délai d'expiration de la requête ; timeout limite aussi l'attente d'interrogation |
pollingInterval | number | 2000 | Fréquence d'interrogation des tâches à jeton |
url / baseUrl | string | selon le transport | Remplace le point d'accès de l'API |
Transports
| Transport | Environnements | Protocole |
|---|---|---|
grpc | Node.js uniquement | gRPC binaire sur HTTP/2 — latence la plus faible, envoie les images en binaire brut |
connect | Node.js et navigateurs | ConnectRPC sur fetch |
http | Node.js et navigateurs | REST/JSON simple sur fetch |
TIP
Dans le navigateur, utilisez connect (recommandé) ou http. Le gRPC natif nécessite Node.js. Avec connect/http, les images sont automatiquement encodées en base64 avant l'envoi ; avec grpc, elles sont envoyées en binaire brut, sans surcharge.
Gestion des erreurs
Toutes les erreurs au niveau de l'API lèvent une SonicError, qui étend la classe Error native. Elle porte un errorId numérique et définit name avec le nom d'erreur correspondant.
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
Les erreurs gRPC transitoires sont relancées automatiquement avec un backoff exponentiel (jusqu'à 3 tentatives) ; vous n'avez donc généralement qu'à gérer les cas SonicError ci-dessus.
Fonctions utilitaires de compte
const balance = await solver.getBalance(); // → number (USD)
const health = await solver.healthCheck(); // → { healthy: boolean, version: string }
Des méthodes de tâche de bas niveau sont disponibles si vous souhaitez un contrôle direct sur la soumission et l'interrogation :
const created = await solver.createTask(task); // submit a Partial<Task>
const result = await solver.getTaskResult(taskId); // poll for a result
Dépannage
require is not defined / Cannot use import statement outside a module — le package est uniquement ESM. Utilisez import dans un projet ESM, ou await import("captchasonic") depuis CommonJS. Voir Installation.
Le transport grpc échoue dans le navigateur — le gRPC natif ne fonctionne que dans Node.js. Passez à transport: "connect" ou transport: "http".
InvalidApiKeyError à chaque appel — vérifiez que la clé est passée en premier argument du constructeur et qu'elle n'est pas accidentellement undefined (par exemple une variable d'environnement absente).
La méthode à jeton expire — les tâches à jeton interrogent jusqu'à timeout ms (120000 par défaut). Augmentez timeout et vérifiez que websiteURL / websiteKey correspondent à la page cible. Pour Cloudflare, un proxy valide est obligatoire.
Les images au chemin de fichier ne se chargent pas — les chemins de fichiers sous forme de chaîne sont lus de façon synchrone et ne fonctionnent que dans Node.js ; dans le navigateur, passez plutôt un Uint8Array.