clientKey to API v2 at api.2captcha.com.
Things to know:
- Every answer is an envelope. 2Captcha returns HTTP 200 for almost everything and reports the outcome in
errorId:0is success, anything else comes with anerrorCodesuch asERROR_ZERO_BALANCE. The plugin throwsTwoCaptchaAPIErrorwith that code, so a resolved promise means the call worked. - Creating a task costs money.
tasks.createcharges the account per task, so it isdestructive. What happens depends on the permissions mode (Permissions):cautiousneeds an approval first (with a database Corsair records the request and the call throws until it is approved; without one the call is refused),strictandreadonlyrefuse it, andopenor no mode runs it. It is not replayed after a 5xx, since the task may already exist; a 429 orERROR_NO_SLOT_AVAILABLE, where nothing was created, is retried. With no funds it answersERROR_ZERO_BALANCE. - Poll for the result.
tasks.resultanswersstatus: "processing"while workers solve the task; poll every 5-10 seconds untilstatusisready, then readsolution(its fields depend on the captcha kind) andcost. - Report outcomes.
account.reportCorrectandaccount.reportIncorrecttake the task id. A rejected answer is reviewed by 2Captcha, which may refund it; the task is not solved again, and a report cannot be taken back. - Captcha kinds.
tasks.createtakes atypesuch asRecaptchaV2TaskProxyless,TurnstileTaskProxylessorImageToTextTask, and the fields that kind needs intask(see https://2captcha.com/api-docs). Kinds without “Proxyless” take your proxy fields. - Retries.
ERROR_NO_SLOT_AVAILABLE(queue full, nothing created) is retried with backoff. Other codes are permanent. A 5xx is retried fortasks.resultandaccount.balanceonly. - No callbacks in this plugin. 2Captcha can POST a result to a registered URL, but this plugin does not receive that delivery; poll
tasks.resultinstead.
- 5 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the 2Captcha API key before the first call: More: API Key
pnpm corsair setup --plugin=twocaptcha --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Read the account balanceWhat’s next
API reference
Every
twocaptcha.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.