CaptchaAI TypeScript SDK

Node.js TypeScript client for the CaptchaAI captcha-solving API.

Call one method per captcha type; the SDK handles HTTP, polling, retries, and error mapping.

Installation

npm install captchaai-javascript

Requirements

Node.js >= 18 (uses native fetch and AbortSignal.timeout).

Quick start

import { CaptchaAI } from "captchaai-javascript";

const solver = new CaptchaAI({ apiKey: "YOUR_32_CHAR_API_KEY" });

const result = await solver.recaptchaV2(
  "YOUR_SITEKEY",
  "https://example.com"
);

console.log(result.solution);
await solver.close();

Configuration

Create a client with your API key. The constructor validates the key and starts a background threadsInfo call to read your account thread cap.

import { CaptchaAI } from "captchaai-javascript";

const solver = new CaptchaAI({
  apiKey: "YOUR_32_CHAR_API_KEY",
  proxy: "user:pass@host:port",       // optional
  proxyType: "HTTP",                  // required when proxy is set
  autoRetry: true,
  baseUrl: "https://ocr.captchaai.com",
  threadBusyTimeoutSeconds: 120,
  maxRetries: 5,                      // optional; overrides autoRetry when set
  networkTimeoutSeconds: 30,
  maxPollSeconds: 180,
  jitterMaxSeconds: 1,
  submitBackoffBaseSeconds: 5,
});

Option	Default	Description
`apiKey`	(required)	32-character CaptchaAI API key
`proxy`	`undefined`	`"user:pass@host:port"` applied to every solve
`proxyType`	`undefined`	`HTTP` / `HTTPS` / `SOCKS4` / `SOCKS5` — required when `proxy` is set
`autoRetry`	`true`	`true` = SDK retries transient errors with backoff; `false` = raise immediately
`baseUrl`	`https://ocr.captchaai.com`	API host for `in.php` / `res.php`
`threadBusyTimeoutSeconds`	`120`	Seconds to keep retrying while all account threads are busy
`maxRetries`	`5` (implicit)	When explicitly set: `0` disables retries; `N > 0` enables up to N submit attempts (supersedes `autoRetry`)
`networkTimeoutSeconds`	`30`	Per-request HTTP timeout
`maxPollSeconds`	`180`	Poll deadline before `TimeoutError`
`jitterMaxSeconds`	`1`	Random jitter added to wait intervals
`submitBackoffBaseSeconds`	`5`	Base interval for exponential submit backoff

A bad key raises InvalidKeyError before any solve runs. Call solver.close() when finished.

Solve result

Every solve method returns a SolveResult:

result.taskId     // string — task ID from submit (always present)
result.solution   // string | string[] | Record<string, unknown> — token, cell indices, or structured answer
result.userAgent  // string | undefined — set for Enterprise / Cloudflare Challenge / CaptchaFox
result.raw        // Record<string, unknown> | undefined — full API response (debugging)
result.rawText    // string | undefined — unparsed solution string before JSON parsing

result.toString() // token string for common token types

Reuse result.userAgent on the target site when it is present (Enterprise reCAPTCHA, Cloudflare Challenge, CaptchaFox).

Normal captcha

Solve a text/image captcha. image may be a file path, URL, data-URI, raw base64, or Uint8Array.

import { CaptchaAI } from "captchaai-javascript";

const solver = new CaptchaAI({ apiKey: "YOUR_32_CHAR_API_KEY" });

const result = await solver.normal("captcha.png", {
  numeric: 1,              // 0=any, 1=digits, 2=letters, 3=digits+letters, 4=no digits
  minLen: 4,
  maxLen: 6,
  phrase: 0,                 // 0=single word, 1=multi-word
  caseSensitive: 0,          // 0=insensitive, 1=case-sensitive
  lang: "en",
  instructions: "Type the characters you see",
});

console.log(result.solution);
await solver.close();

Grid captcha

Solve a tile-selection captcha. gridSize must be "3x3" or "4x4". solution is a list of cell indices.

const result = await solver.grid(
  "grid.png",
  "select all traffic lights",
  "3x3"
);

console.log(result.solution);

BLS captcha

Solve a BLS multi-image captcha. Pass exactly 9 images (path/URL/base64/Uint8Array each). solution is a list of cell indices.

const result = await solver.bls(
  Array.from({ length: 9 }, (_, i) => `img${i}.png`),
  "YOUR_INSTRUCTIONS"
);

console.log(result.solution);

reCAPTCHA v2

Solve reCAPTCHA v2 (standard, invisible, or enterprise). Pass sitekey and page url. Enterprise results include userAgent.

If both enterprise and invisible are set, enterprise takes precedence.

// Standard
const result = await solver.recaptchaV2(
  "YOUR_SITEKEY",
  "https://example.com"
);
console.log(result.solution);

// Invisible
await solver.recaptchaV2("YOUR_SITEKEY", "https://example.com", {
  invisible: true,
});

// Enterprise (optional action; result may include userAgent)
const enterprise = await solver.recaptchaV2("YOUR_SITEKEY", "https://example.com", {
  enterprise: true,
  action: "login",
});
console.log(enterprise.solution, enterprise.userAgent);