Skip to content
CaptchaSonic

SDK Node.js

Biblioteca oficial da CaptchaSonic para Node.js e TypeScript — moderna, baseada em Promises, com múltiplos transportes (gRPC / ConnectRPC / HTTP).

O SDK Node.js da CaptchaSonic (captchasonic) é uma biblioteca moderna, baseada em Promises e com TypeScript em primeiro lugar, para resolver CAPTCHAs em grande escala. Todos os métodos retornam uma Promise, incluem definições de tipos completas e funcionam sobre três transportes intercambiáveis — gRPC nativo (o mais rápido, somente Node.js), ConnectRPC (funciona em Node.js e navegadores) e HTTP/JSON simples. Erros transitórios são repetidos automaticamente com backoff exponencial.

Ele funciona no Node.js ≥ 18 e em navegadores modernos, e é compatível com Express, Fastify, Next.js, React, Vue e Vite.


Instalação

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

Requisitos

RequisitoObservações
Node.js≥ 18.0.0 (necessário para o transporte grpc)
Formato de móduloES Module — o pacote inclui "type": "module"
NavegadorQualquer navegador moderno com fetch; use o transporte connect ou http

O pacote é publicado somente como ESM. Em um projeto ESM ("type": "module" no seu package.json, ou um arquivo .mjs), importe-o diretamente:

import { CaptchaSonic } from "captchasonic";

A partir de um arquivo CommonJS, carregue-o com um import() dinâmico:

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

TIP

Se você usa TypeScript, defina "module": "NodeNext" (ou "ESNext") e "moduleResolution": "NodeNext" no tsconfig.json para que as definições de tipos incluídas sejam resolvidas corretamente.


Autenticação

Crie uma API key no dashboard da CaptchaSonic e passe-a como primeiro argumento do construtor:

import { CaptchaSonic } from "captchasonic";

const solver = new CaptchaSonic("YOUR_API_KEY");

Nunca deixe chaves fixas no controle de versão. Leia a chave do ambiente:

import { CaptchaSonic } from "captchasonic";

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

Início rápido

Cada tipo de captcha tem um helper solve* dedicado que envia a tarefa e resolve com o resultado. Não há uma etapa separada de polling para tarefas de imagem — o SDK cuida disso para você.

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

Retorno: os métodos de imagem resolvem com um resultado cuja resposta fica em typedSolution (ex.: typedSolution.grid.objects, os índices dos blocos selecionados); os métodos de token retornam o token no mapa solution.

TIP

Os métodos baseados em token (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, popular-captcha token) enviam uma tarefa de automação de navegador e fazem polling internamente até o token estar pronto — por padrão, por até 120 segundos.


Tipos de CAPTCHA suportados

Todos os métodos de imagem recebem um único objeto de opções tipado. As imagens podem ser Uint8Array, Buffer do Node ou um caminho de arquivo em string (caminhos de arquivo são exclusivos do Node.js).

reCAPTCHA v2 (imagem)

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

Retorno: os tipos de grade/clique ficam em typedSolution.grid.objects (ou typedSolution.click); o tipo slide retorna typedSolution.slide.x.

Aliases aceitos em type:

CanônicoAliases
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 / imagem para 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]
OpçãoTipoObservações
module"common" | "mtcaptcha" | "bls" | "morocco"Padrão "common"
numericbooleanSomente dígitos (ativado automaticamente para "bls")
caseSensitivebooleanPreserva maiúsculas e minúsculas
minLength / maxLengthnumberLimites de comprimento

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

Retorno: click fica em typedSolution.click; whirl/slide retornam typedSolution.slide.x.

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

Retorno: grid fica em typedSolution.grid.objects; slide retorna typedSolution.slide.x.

type aceita "grid"/"binance_grid" e "slide"/"binance_slide".

AWS WAF

solveAwsWaf recebe argumentos posicionais. A question é formatada como "type:category:target".

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

Retorno: os índices dos blocos selecionados ficam em typedSolution.grid.objects.

Imagem slide (local, sem IA)

Detecta o deslocamento do slide localmente usando detecção de contornos. Aceita uma imagem combinada 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

Retorno: o deslocamento do slide em pixels em typedSolution.slide.x.

Métodos de token (automação de navegador)

Esses métodos enviam uma tarefa e fazem polling internamente até que um token seja retornado (até o timeout de polling, 120 s por padrão).

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

Retorno: o token fica no mapa solution da resposta (por exemplo result.solution.token ou result.solution.gRecaptchaResponse, conforme o captcha).


Uso com TypeScript

O SDK exporta tipos para cada objeto de opções e resposta. Importe-os com 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 é Uint8Array | Buffer | string.


Suporte a proxy

Os métodos de token / automação de navegador aceitam uma string opcional proxy no formato http://user:pass@host:port:

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

WARNING

solveCloudflare sempre exige um proxy — o campo proxy é obrigatório nesse método. Os demais métodos de token rodam sem proxy quando proxy é omitido.

Para o hCaptcha corporativo, você também pode passar metadata (rqdata, rqtoken, fingerprint) para solvePopularCaptchaToken.


Configuração

Passe um objeto de opções como segundo argumento do construtor. Apenas as opções abaixo são suportadas.

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)
});
OpçãoTipoPadrãoDescrição
transport"grpc" | "connect" | "http""grpc"Protocolo de transporte (veja a tabela abaixo)
timeout / timeoutMsnumber30000 por chamadaTimeout da requisição; timeout também limita o tempo de espera do polling
pollingIntervalnumber2000Frequência com que as tarefas de token são consultadas
url / baseUrlstringpor transporteSubstitui o endpoint da API

Transportes

TransporteAmbientesProtocolo
grpcSomente Node.jsgRPC binário sobre HTTP/2 — menor latência, envia imagens como binário bruto
connectNode.js e navegadoresConnectRPC sobre fetch
httpNode.js e navegadoresREST/JSON simples sobre fetch

TIP

No navegador, use connect (recomendado) ou http. O gRPC nativo requer Node.js. Com connect/http, as imagens são codificadas automaticamente em base64 antes do envio; com grpc, são enviadas como binário bruto, sem overhead.


Tratamento de erros

Todas as falhas no nível da API lançam um SonicError, que estende o Error nativo. Ele carrega um errorId numérico e define name com o nome do erro correspondente.

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

Erros transitórios de gRPC são repetidos automaticamente com backoff exponencial (até 3 tentativas), então normalmente você só precisa tratar os casos de SonicError acima.


Funções auxiliares da conta

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

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

Métodos de tarefa de baixo nível estão disponíveis se você precisar de controle direto sobre o envio e o polling:

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

Solução de problemas

require is not defined / Cannot use import statement outside a module — o pacote é somente ESM. Use import em um projeto ESM, ou await import("captchasonic") a partir de CommonJS. Veja Instalação.

O transporte grpc falha no navegador — o gRPC nativo é exclusivo do Node.js. Troque para transport: "connect" ou transport: "http".

InvalidApiKeyError em todas as chamadas — confirme que a chave é passada como primeiro argumento do construtor e não está undefined por acidente (por exemplo, uma variável de ambiente ausente).

Método de token expira por timeout — tarefas de token fazem polling por até timeout ms (padrão 120000). Aumente timeout e verifique se websiteURL / websiteKey correspondem à página alvo. Para o Cloudflare, é obrigatório um proxy válido.

Imagens por caminho de arquivo não carregam — caminhos de arquivo em string são lidos de forma síncrona e são exclusivos do Node.js; no navegador, passe um Uint8Array.


Recursos