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
要件
| Requirement | Notes |
|---|---|
| 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 が自動で処理します。
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 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 の別名:
| Canonical | 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 / 画像からテキスト
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]
| Option | Type | Notes |
|---|---|---|
module | "common" | "mtcaptcha" | "bls" | "morocco" | 既定値は "common" |
numeric | boolean | 数字のみ("bls" では自動で設定されます) |
caseSensitive | boolean | 英字の大文字と小文字を区別します |
minLength / maxLength | number | 文字列の長さの上限と下限 |
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 秒)。
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 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)
});
| Option | Type | Default | Description |
|---|---|---|---|
transport | "grpc" | "connect" | "http" | "grpc" | 通信プロトコル(下の表を参照) |
timeout / timeoutMs | number | 呼び出しごとに 30000 | リクエストのタイムアウトです。timeout はポーリングの待機時間の上限にもなります。 |
pollingInterval | number | 2000 | トークンタスクをポーリングする間隔です。 |
url / baseUrl | string | トランスポートごとに異なる | API のエンドポイントを上書きします。 |
トランスポート
| Transport | Environments | Protocol |
|---|---|---|
grpc | Node.js のみ | HTTP/2 上の gRPC バイナリ — 最も低遅延で、画像を生のバイナリとして送信します |
connect | Node.js とブラウザ | fetch 上の ConnectRPC |
http | Node.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
}
}
| 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
一時的な 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 を渡してください。