BILSOLVER API
A private captcha-solving API for Cloudflare Turnstile and Aliyun captcha. If you have used 2Captcha or CapMonster, the flow is identical — only the base URL changes.
Introduction
Every request is JSON over HTTPS. The base URL is:
You solve a captcha in two calls: createTask submits the job and returns a taskId; getTaskResult polls that id until the token is ready. You are charged only for solves that land — failed tasks are refunded automatically.
Authentication
Every request carries your clientKey in the JSON body. There are no headers to sign.
The solve flow
# 1 — create a task curl -X POST https://bilsolver.com/createTask \ -H "Content-Type: application/json" \ -d '{ "clientKey": "YOUR_API_KEY", "task": { "type": "TurnstileTaskProxyless", "websiteURL": "https://example.com", "websiteKey": "0xAAA..." } }' # → { "errorId": 0, "taskId": 84123901 } # 2 — poll for the result curl -X POST https://bilsolver.com/getTaskResult \ -H "Content-Type: application/json" \ -d '{ "clientKey": "YOUR_API_KEY", "taskId": 84123901 }' # → { "errorId": 0, "status": "ready", "solution": { "token": "0.AB..." } }
createTask
Submits a captcha job. Returns a taskId immediately; solving happens on the cluster in the background.
| Field | Type | Description |
|---|---|---|
| clientKeyrequired | string | Your API key. |
| taskrequired | object | The task object — see task types. Its type field selects the captcha. |
| callbackUrloptional | string | An https URL — the result is POSTed here when ready. See callbacks. |
Response — { "errorId": 0, "taskId": <number> }. On error, errorId: 1 with an errorCode and errorDescription.
getTaskResult
Polls a task. Poll every 2–3 seconds. A typical solve takes 1–5 seconds.
| Field | Type | Description |
|---|---|---|
| clientKeyrequired | string | Your API key. |
| taskIdrequired | number | The id returned by createTask. |
While solving: { "errorId": 0, "status": "processing" }
When ready: { "errorId": 0, "status": "ready", "solution": { "token": "…" } }
getBalance
Returns your remaining balance in USD.
curl -X POST https://bilsolver.com/getBalance \ -d '{ "clientKey": "YOUR_API_KEY" }' # → { "errorId": 0, "balance": 9.87 }
health & stats
/health returns service status. /stats returns live cluster metrics — solved count, success rate, workers online and uptime. Both are public and unauthenticated.
Cloudflare Turnstile
Type TurnstileTask (with proxy) or TurnstileTaskProxyless. Price $0.002 / solve.
| Field | Type | Description |
|---|---|---|
| typerequired | string | TurnstileTask or TurnstileTaskProxyless. |
| websiteURLrequired | string | The page URL where the widget appears. |
| websiteKeyrequired | string | The Turnstile sitekey (0x…). |
| actionoptional | string | The widget action, if set. |
| cDataoptional | string | The widget cData, if set. |
| proxyURLproxy only | string | See proxy format. |
Solution: { "token": "…", "userAgent": "…" } — resubmit the token under the returned userAgent.
Aliyun Captcha V2
Type AliyunV2Task / AliyunV2TaskProxyless. Price $0.003 / solve.
| Field | Type | Description |
|---|---|---|
| typerequired | string | AliyunV2Task or AliyunV2TaskProxyless. |
| websiteURLrequired | string | The page URL hosting the captcha. |
| websiteKeyrequired | string | The Aliyun sceneId. |
| prefixrequired | string | The Aliyun prefix for the scene. |
| proxyURLproxy only | string | See proxy format. |
Aliyun Captcha V3
Type AliyunV3Task / AliyunV3TaskProxyless. Price $0.004 / solve. Same fields as V2 (websiteURL, websiteKey=sceneId, prefix).
GeeTest v4 — slide puzzle
Type GeeTestTask / GeeTestTaskProxyless. Price $0.003 / solve. The cluster runs the genuine gcaptcha4.js + device-check (gct4) in a real browser, computes the puzzle offset from the original images and returns the one-time seccode. Typical time 4–7 s.
| Field | Type | Description |
|---|---|---|
| typerequired | string | GeeTestTask or GeeTestTaskProxyless. |
| websiteURLrequired | string | The page URL hosting the captcha (used as origin/referer). |
| websiteKeyrequired | string | The GeeTest v4 captcha_id (32 hex). The API cluster (gcaptcha4.geetest.com vs cap-global.geelabapi.com) is detected automatically. |
| challengev3 only | string | Set only for GeeTest v3 (gt + challenge); leave empty for v4. |
| geetestApiServeroptional | string | Force an API host, e.g. cap-global.geelabapi.com. |
| languageoptional | string | Widget language, default ind. |
| proxyURLproxy only | string | See proxy format. GeeTest scores IP reputation — residential proxies recommended. |
Solution — the four seccode fields, valid once, use within ~2 minutes:
{ "captcha_id": "c3d8…c8a", "lot_number": "cc66…70b0", "pass_token": "f4c1…be58",
"gen_time": "1790928168", "captcha_output": "TvF1oeQu…", "userAgent": "…" }Only captcha_type: slide is supported today (icon / gobang / word variants return ERROR_CAPTCHA_UNSOLVABLE and are refunded).
POST /solve — one-call GeeTest shortcut
A synchronous endpoint for GeeTest v4 slide: one request, the seccode comes back in the response (no polling). Authenticate with clientKey in the body, header X-API-Key, or Authorization: Bearer.
POST https://bilsolver.com/solve { "captcha_id": "c3d8008a02df4f35258affa660653c8a", "proxy": "http://user:pass@host:port" } # optional # 200 OK { "status": "ok", "lot_number": "…", "pass_token": "…", "gen_time": "…", "captcha_output": "…", "elapsed_ms": 5400 } # failure (balance refunded) { "status": "fail", "reason": "verify_failed | load_failed | timeout", "detail": "…" }
Optional fields: website_url, lang (default ind), api_server. Up to 2 attempts are made inside the call (max ≈ 90 s); each seccode is single-use — never cache it.
Image OCR — 4-digit captcha
Synchronous OCR for numeric image captchas (4 digits, noise lines/dots, light rotation). Send the image as base64, with or without the data:image/…;base64, prefix. Price $0.0005 per successful read; failures are free. Typical latency 5–60 ms; 99.8% on a 10-style benchmark.
POST https://bilsolver.com/ocr # header X-API-Key: bil_u_… { "image": "iVBORw0KGgo…" } # 200 { "code": 200, "result": "3847", "confidence": 0.95 } # 400 (refunded) { "code": 400, "result": "", "error": "could not detect 4 digits" }
Health: GET /ocr/health. Use a 5 s client timeout and fetch a fresh captcha instead of retrying the same image.
reCAPTCHA v2 / v3
RecaptchaV3Task(Proxyless) $0.0025 — fields websiteURL, websiteKey, optional pageAction, minScore. Solution { "token", "userAgent" }.
RecaptchaV2Task(Proxyless) $0.002 — fields websiteURL, websiteKey, optional isInvisible, recaptchaDataSValue. Solution { "gRecaptchaResponse", "userAgent" }.
hCaptcha
HCaptchaTask(Proxyless) $0.003 — fields websiteURL, websiteKey, optional isInvisible, enterprisePayload. Solution { "gRecaptchaResponse", "userAgent" }.
Report verify result (Aliyun)
Aliyun tokens are verified by your backend (VerifyCaptchaV3 with your AccessKey). Report the outcome so the cluster can track real pass rates and tune the solver. Free, one call per task.
POST https://bilsolver.com/reportTaskResult { "clientKey": "bil_u_…", "taskId": 84123901, "verifyCode": "T001" } # or "F015", "F001", … GET https://bilsolver.com/feedbackStats?clientKey=bil_u_…&days=1 # your pass rate per task type
Proxy format
For the non-proxyless task types, pass proxyURL as a full URL:
http://user:pass@host:port http://host:port socks5://user:pass@host:port
Proxyless task types run through the cluster's own egress — no proxy needed.
Callbacks (webhooks)
Add callbackUrl to createTask and skip polling. When the task finishes, BILSOLVER POSTs the result to your URL:
# ready { "taskId": 84123901, "status": "ready", "errorId": 0, "solution": { "token": "…" } } # failed (refunded) { "taskId": 84123901, "status": "failed", "errorId": 1, "errorCode": "ERROR_CAPTCHA_UNSOLVABLE" }
Callbacks are retried up to 3 times (0s, 2s, 5s) on non-2xx responses.
Error codes
| Code | Meaning |
|---|---|
| ERROR_KEY_DOES_NOT_EXIST | The clientKey is not recognised. |
| ERROR_ZERO_BALANCE | Account balance is zero — top up to continue. |
| ERROR_NO_SUCH_TASK | Task not found or expired (tasks live ~15 min). |
| ERROR_WRONG_TASK_TYPE | Unknown task type, or not allowed for this key. |
| ERROR_WRONG_WEBSITEURL | Missing or invalid websiteURL. |
| ERROR_WRONG_WEBSITEKEY | Missing sitekey / sceneId. |
| ERROR_WRONG_PREFIX | Missing prefix (Aliyun). |
| ERROR_NO_SLOT_AVAILABLE | Cluster busy — retry in a few seconds. |
| ERROR_CAPTCHA_UNSOLVABLE | The captcha could not be solved after retries — refunded. |