Skip to content
CaptchaSonic

Node.js SDK

Node.js と TypeScript 向けの公式 CaptchaSonic ライブラリです。モダンで Promise ベース、複数のトランスポート(gRPC / ConnectRPC / HTTP)に対応しています。

CaptchaSonic Node.js SDK(captchasonic)は、大量の CAPTCHA を解決するためのモダンで Promise ベースの TypeScript ファーストのライブラリです。すべてのメソッドは Promise を返し、完全な型定義を備えています。3 つの交換可能なトランスポートで動作します。ネイティブの gRPC(最速、Node.js のみ)、ConnectRPC(Node.js とブラウザの両方で動作)、そして通常の HTTP/JSON です。一時的なエラーは、指数バックオフで自動的に再試行されます。

Node.js ≥ 18 と最新のブラウザで動作し、Express、Fastify、Next.js、React、Vue、Vite と互換性があります。


インストール

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

要件

RequirementNotes
Node.js≥ 18.0.0(grpc トランスポートに必要)
モジュール形式ES Module — パッケージは "type": "module" を含みます
ブラウザfetch に対応した最新のブラウザ。connect または http トランスポートを使用してください

このパッケージは ESM のみ で公開されています。ESM のプロジェクト(package.json に "type": "module" がある、または .mjs ファイル)では、直接インポートしてください。

import { CaptchaSonic } from "captchasonic";

CommonJS のファイルからは、動的な import() で読み込んでください。

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

TIP

TypeScript を使う場合は、同梱の型定義を正しく解決できるように、tsconfig.json で "module": "NodeNext"(または "ESNext")と "moduleResolution": "NodeNext" を設定してください。


認証

CaptchaSonic ダッシュボード で API キーを作成し、コンストラクターの最初の引数として渡します。

import { CaptchaSonic } from "captchasonic";

const solver = new CaptchaSonic("YOUR_API_KEY");

キーをソース管理にハードコードしないでください。代わりに環境変数から読み込んでください。

import { CaptchaSonic } from "captchasonic";

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

クイックスタート

CAPTCHA の種別ごとに専用の solve* ヘルパーがあり、タスクを送信して結果を解決します。画像タスクには個別のポーリング手順はありません。SDK が自動で処理します。

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

戻り値: 画像メソッドは、回答が typedSolution の下にある結果を返します(例: typedSolution.grid.objects、選択したタイルのインデックス)。トークンメソッドは、solution のマップにトークンを格納して返します。

TIP

トークン型のメソッド(Turnstile、Cloudflare、reCAPTCHA v2/v3 トークン、popular-captcha トークン)は、ブラウザ自動化のタスクを送信し、トークンの準備ができるまで内部でポーリングします。既定では最大 120 秒です。


対応している CAPTCHA 種別

すべての画像メソッドは、型付きのオプションオブジェクトを 1 つ受け取ります。画像は Uint8Array、Node の Buffer、または文字列のファイルパスで指定できます(ファイルパスは Node.js でのみ使えます)。

reCAPTCHA v2(画像)

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

戻り値: grid/click の種別は typedSolution.grid.objects(または typedSolution.click)に入ります。slide は typedSolution.slide.x を返します。

受け付ける type の別名:

CanonicalAliases
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 / 画像からテキスト

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]
OptionTypeNotes
module"common" | "mtcaptcha" | "bls" | "morocco"既定値は "common"
numericboolean数字のみ("bls" では自動で設定されます)
caseSensitiveboolean英字の大文字と小文字を区別します
minLength / maxLengthnumber文字列の長さの上限と下限

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

戻り値: click は typedSolution.click に入ります。whirl / slide は typedSolution.slide.x を返します。

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

戻り値: grid は typedSolution.grid.objects に入ります。slide は typedSolution.slide.x を返します。

type には "grid" / "binance_grid"、"slide" / "binance_slide" を指定できます。

AWS WAF

solveAwsWaf は位置引数を受け取ります。question は "type:category:target" の形式で指定します。

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

戻り値: 選択したタイルのインデックスが typedSolution.grid.objects に入ります。

スライド画像(ローカル処理、AI は使用しません)

輪郭検出を使って、スライドのオフセットをローカルで検出します。1 枚の結合画像、または [background, piece] を受け付けます。

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

戻り値: スライドのオフセット(ピクセル)が typedSolution.slide.x に入ります。

トークンメソッド(ブラウザ自動化)

これらはタスクを送信し、トークンが返るまで内部でポーリングします(ポーリングのタイムアウトまで、既定では 120 秒)。

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

戻り値: トークンはレスポンスの solution マップに入ります(例: CAPTCHA の種類に応じて result.solution.token や result.solution.gRecaptchaResponse)。


TypeScript での利用

SDK は、すべてのオプションオブジェクトとレスポンスの型をエクスポートしています。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);

エクスポートされている型

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 です。


プロキシのサポート

トークン / ブラウザ自動化メソッドは、http://user:pass@host:port の形式の任意の proxy 文字列を受け付けます。

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

WARNING

solveCloudflare は 常に プロキシを必要とします。このメソッドでは proxy フィールドは必須です。他のトークンメソッドは、proxy を省略するとプロキシなしで実行されます。

エンタープライズ向けの hCaptcha では、solvePopularCaptchaToken に metadata(rqdata、rqtoken、fingerprint)を渡すこともできます。


設定

2 番目のコンストラクター引数としてオプションオブジェクトを渡します。以下のオプションのみサポートされています。

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)
});
OptionTypeDefaultDescription
transport"grpc" | "connect" | "http""grpc"通信プロトコル(下の表を参照)
timeout / timeoutMsnumber呼び出しごとに 30000リクエストのタイムアウトです。timeout はポーリングの待機時間の上限にもなります。
pollingIntervalnumber2000トークンタスクをポーリングする間隔です。
url / baseUrlstringトランスポートごとに異なるAPI のエンドポイントを上書きします。

トランスポート

TransportEnvironmentsProtocol
grpcNode.js のみHTTP/2 上の gRPC バイナリ — 最も低遅延で、画像を生のバイナリとして送信します
connectNode.js とブラウザfetch 上の ConnectRPC
httpNode.js とブラウザfetch 上の通常の REST/JSON

TIP

ブラウザでは connect(推奨)または http を使ってください。ネイティブの gRPC は Node.js が必要です。connect / http では、送信前に画像が自動で base64 にエンコードされます。grpc では、オーバーヘッドなしで生のバイナリとして送信されます。


エラー処理

API レベルの失敗はすべて SonicError を送出します。これは組み込みの Error を拡張したものです。数値の errorId を持ち、name には対応するエラー名が設定されます。

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

一時的な gRPC エラーは、指数バックオフで自動的に再試行されます(最大 3 回)。そのため、通常は上記の SonicError のケースだけを扱えば十分です。


アカウントのヘルパー

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

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

送信とポーリングを直接制御する必要がある場合は、低レベルのタスクメソッドも利用できます。

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

トラブルシューティング

require is not defined / Cannot use import statement outside a module — このパッケージは ESM のみです。ESM のプロジェクトでは import を使うか、CommonJS からは await import("captchasonic") を使ってください。詳しくは インストール を参照してください。

ブラウザで grpc トランスポートが失敗する — ネイティブの gRPC は Node.js のみです。transport: "connect" または transport: "http" に切り替えてください。

すべての呼び出しで InvalidApiKeyError が出る — キーがコンストラクターの最初の引数として渡されていること、また誤って undefined になっていないこと(環境変数の未設定など)を確認してください。

トークンメソッドがタイムアウトする — トークンタスクは timeout ミリ秒(既定値 120000)までポーリングします。timeout を大きくし、websiteURL / websiteKey が対象ページと一致しているか確認してください。Cloudflare では、有効な proxy が必須です。

ファイルパスの画像が読み込めない — 文字列のファイルパスは同期的に読み込まれ、Node.js でのみ使えます。ブラウザでは代わりに Uint8Array を渡してください。


リソース