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
| Requisito | Observações |
|---|---|
| Node.js | ≥ 18.0.0 (necessário para o transporte grpc) |
| Formato de módulo | ES Module — o pacote inclui "type": "module" |
| Navegador | Qualquer 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ê.
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 fieldRetorno: 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 mapasolution.
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ônico | Aliases |
|---|---|
| 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ção | Tipo | Observações |
|---|---|---|
module | "common" | "mtcaptcha" | "bls" | "morocco" | Padrão "common" |
numeric | boolean | Somente dígitos (ativado automaticamente para "bls") |
caseSensitive | boolean | Preserva maiúsculas e minúsculas |
minLength / maxLength | number | Limites 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).
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 REQUIREDRetorno: 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ção | Tipo | Padrão | Descrição |
|---|---|---|---|
transport | "grpc" | "connect" | "http" | "grpc" | Protocolo de transporte (veja a tabela abaixo) |
timeout / timeoutMs | number | 30000 por chamada | Timeout da requisição; timeout também limita o tempo de espera do polling |
pollingInterval | number | 2000 | Frequência com que as tarefas de token são consultadas |
url / baseUrl | string | por transporte | Substitui o endpoint da API |
Transportes
| Transporte | Ambientes | Protocolo |
|---|---|---|
grpc | Somente Node.js | gRPC binário sobre HTTP/2 — menor latência, envia imagens como binário bruto |
connect | Node.js e navegadores | ConnectRPC sobre fetch |
http | Node.js e navegadores | REST/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
}
}
| 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
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.