Skip to content
CaptchaSonic

SDK de Node.js

Biblioteca oficial de CaptchaSonic para Node.js y TypeScript — moderna, basada en Promises, con múltiples transportes (gRPC / ConnectRPC / HTTP).

El SDK de Node.js de CaptchaSonic (captchasonic) es una biblioteca moderna, basada en Promises y orientada a TypeScript, para resolver CAPTCHAs a gran escala. Cada método devuelve una Promise, incluye definiciones de tipos completas y funciona con tres transportes intercambiables: gRPC nativo (el más rápido, solo Node.js), ConnectRPC (funciona en Node.js y en navegadores) y HTTP/JSON sencillo. Los errores transitorios se reintentan automáticamente con retroceso exponencial.

Funciona en Node.js ≥ 18 y en navegadores modernos, y es compatible con Express, Fastify, Next.js, React, Vue y Vite.


Instalación

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

Requisitos

RequisitoNotas
Node.js≥ 18.0.0 (necesario para el transporte grpc)
Formato de móduloES Module: el paquete incluye "type": "module"
NavegadorCualquier navegador moderno con fetch; usa el transporte connect o http

El paquete se publica solo como ESM. En un proyecto ESM ("type": "module" en tu package.json, o un archivo .mjs), impórtalo directamente:

import { CaptchaSonic } from "captchasonic";

Desde un archivo CommonJS, cárgalo con un import() dinámico:

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

TIP

Si usas TypeScript, define "module": "NodeNext" (o "ESNext") y "moduleResolution": "NodeNext" en tsconfig.json para que las definiciones de tipos incluidas se resuelvan correctamente.


Autenticación

Crea una clave API en el panel de CaptchaSonic y pásala como primer argumento del constructor:

import { CaptchaSonic } from "captchasonic";

const solver = new CaptchaSonic("YOUR_API_KEY");

Nunca incluyas claves en el código fuente del control de versiones. Léela desde el entorno:

import { CaptchaSonic } from "captchasonic";

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

Inicio rápido

Cada tipo de CAPTCHA tiene un ayudante solve* dedicado que envía la tarea y se resuelve con el resultado. No hay un paso de sondeo aparte para las tareas de imagen: el SDK lo gestiona por ti.

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

Devuelve: los métodos de imagen resuelven un resultado cuya respuesta está en typedSolution (p. ej., typedSolution.grid.objects, los índices de las casillas seleccionadas); los métodos de token devuelven el token en el mapa solution.

TIP

Los métodos basados en token (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, token de popular-captcha) envían una tarea de automatización de navegador y sondean internamente hasta que el token está listo; por defecto, hasta 120 segundos.


Tipos de CAPTCHA compatibles

Todos los métodos de imagen reciben un único objeto de opciones tipado. Las imágenes pueden ser Uint8Array, Buffer de Node o una ruta de archivo en forma de cadena (las rutas de archivo solo funcionan en Node.js).

reCAPTCHA v2 (imagen)

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

Devuelve: los tipos grid/click van a typedSolution.grid.objects (o typedSolution.click); slide devuelve typedSolution.slide.x.

Alias aceptados en type:

CanónicoAlias
cuadrícula de 9"nine", "geetest_nine", "9"
click / icono"click", "geetest_click", "icon"
deslizar"slide", "geetest_slide"
coincidencia"match", "geetest_match"
winlinze"winlinze", "geetest_winlinze"

OCR / imagen a texto

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]
OpciónTipoNotas
module"common" | "mtcaptcha" | "bls" | "morocco"Predeterminado "common"
numericbooleanSolo dígitos (se activa automáticamente para "bls")
caseSensitivebooleanConserva las mayúsculas y minúsculas
minLength / maxLengthnumberLímites de longitud

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

Devuelve: click va a typedSolution.click; whirl/slide devuelven typedSolution.slide.x.

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

Devuelve: grid va a typedSolution.grid.objects; slide devuelve typedSolution.slide.x.

type acepta "grid"/"binance_grid" y "slide"/"binance_slide".

AWS WAF

solveAwsWaf recibe argumentos posicionales. La question tiene el formato "type:category:target".

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

Devuelve: los índices de las casillas seleccionadas en typedSolution.grid.objects.

Imagen de slide (local, sin IA)

Detecta el desplazamiento del slide localmente mediante detección de contornos. Acepta una imagen combinada o [background, piece].

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

Devuelve: el desplazamiento del slide en píxeles en typedSolution.slide.x.

Métodos de token (automatización de navegador)

Estos envían una tarea y sondean internamente hasta que se devuelve un token (hasta el tiempo límite de sondeo, 120 s por defecto).

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

Devuelve: el token en el mapa solution de la respuesta (por ejemplo, result.solution.token o result.solution.gRecaptchaResponse, según el CAPTCHA).


Uso con TypeScript

El SDK exporta tipos para cada objeto de opciones y de respuesta. Impórtalos con 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);

Tipos exportados

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


Compatibilidad con proxy

Los métodos de token y de automatización de navegador aceptan una cadena proxy opcional con el formato http://user:pass@host:port:

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

WARNING

solveCloudflare siempre requiere un proxy: el campo proxy es obligatorio para ese método. Los demás métodos de token se ejecutan sin proxy cuando se omite proxy.

Para hCaptcha empresarial también puedes pasar metadata (rqdata, rqtoken, fingerprint) a solvePopularCaptchaToken.


Configuración

Pasa un objeto de opciones como segundo argumento del constructor. Solo se admiten las opciones siguientes.

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)
});
OpciónTipoPredeterminadoDescripción
transport"grpc" | "connect" | "http""grpc"Protocolo de transmisión (ver la tabla siguiente)
timeout / timeoutMsnumber30000 por llamadaTiempo límite de la petición; timeout también limita la espera del sondeo
pollingIntervalnumber2000Frecuencia con la que se sondean las tareas de token
url / baseUrlstringsegún el transporteSustituye el endpoint de la API

Transportes

TransporteEntornosProtocolo
grpcSolo Node.jsgRPC binario sobre HTTP/2: menor latencia, envía las imágenes como binario sin procesar
connectNode.js y navegadoresConnectRPC sobre fetch
httpNode.js y navegadoresREST/JSON sencillo sobre fetch

TIP

En el navegador usa connect (recomendado) o http. El gRPC nativo requiere Node.js. Con connect/http, las imágenes se codifican automáticamente en base64 antes de enviarse; con grpc se envían como binario sin procesar, sin sobrecarga.


Manejo de errores

Todos los fallos a nivel de API lanzan un SonicError, que extiende el Error integrado. Incluye un errorId numérico y asigna a name el nombre del error correspondiente.

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

Los errores transitorios de gRPC se reintentan automáticamente con retroceso exponencial (hasta 3 intentos), así que normalmente solo necesitas gestionar los casos de SonicError de arriba.


Ayudantes de cuenta

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

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

Los métodos de tarea de bajo nivel están disponibles si necesitas control directo sobre el envío y el sondeo:

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

Solución de problemas

require is not defined / Cannot use import statement outside a module: el paquete es solo ESM. Usa import en un proyecto ESM, o await import("captchasonic") desde CommonJS. Consulta Instalación.

El transporte grpc falla en el navegador: el gRPC nativo es solo para Node.js. Cambia a transport: "connect" o transport: "http".

InvalidApiKeyError en cada llamada: confirma que la clave se pasa como primer argumento del constructor y que no es undefined por accidente (por ejemplo, una variable de entorno que falta).

El método de token agota el tiempo de espera: las tareas de token sondean hasta timeout ms (por defecto 120000). Aumenta timeout y verifica que websiteURL / websiteKey coincidan con la página de destino. En Cloudflare es obligatorio un proxy válido.

Las imágenes con ruta de archivo no se cargan: las rutas de archivo en forma de cadena se leen de forma síncrona y solo son válidas en Node.js; en el navegador pasa un Uint8Array en su lugar.


Recursos