Task Lifecycle

How a solve flows through CaptchaKings: submission, processing, results, retries, and billing.

Two Integration Styles

CaptchaKings exposes two API styles. Pick the one that matches your captcha type:

Style Endpoints Covers Result Delivery
Synchronous JSON (recommended) POST /api/process.php, /api/tencent.php, /api/geetest.php, /api/xcaptcha.php, /api/mtcaptcha.php, /api/amazon.php All supported types In the same HTTP response — no polling, no task IDs
2Captcha-compatible pair POST /in.php + GET /res.php (also under /api/) xCaptcha only Task ID from in.php, answer via res.php?action=get
Important: the legacy in.php/res.php pair currently routes every uploaded image to the xCaptcha pipeline — the method parameter is accepted for compatibility but does not change routing. For any other captcha type, use its native synchronous endpoint.

1. Synchronous Flow (Native Endpoints)

text 
Client                          CaptchaKings
  |                                   |
  |--- POST /api/process.php ------>  |  1. Auth + balance check
  |     (image, API key)              |  2. Solve (AI pipeline)
  |                                   |  3. Charge on success
  |<---- 200 {"success":true, ...} --|  4. Return prediction

One request in, one response out. Successful solves are billed; rejected requests (4xx) are never billed.

2. Task-Based Flow (2Captcha-Compatible, xCaptcha Only)

Step 1 — Submit the image to in.php. The response is either plain text or JSON when you pass json=1:

text 
OK|74563891234

-- or with json=1 --
{"status": 1, "request": "74563891234"}

Step 2 — Retrieve with res.php?key=YOUR_KEY&action=get&id=74563891234:

text 
OK|7HkP2

-- or with json=1 --
{"status": 1, "request": "7HkP2"}

Because images are solved synchronously before in.php responds, the answer is already stored when you receive the task ID — the first res.php poll normally returns the result immediately. If you poll anyway, wait 2–5 seconds between attempts and give up after 30 seconds.

res.php?key=YOUR_KEY&action=getbalance returns your current balance as a plain number.

Retries & Idempotency

Situation Billed? What To Do
4xx error (invalid key, no file, invalid image) No Fix the request; safe to retry immediately
429 Too Many Requests No Wait 60 seconds (per-minute window), then retry — see Rate Limits
5xx / network timeout No (solve not recorded) Retry with exponential backoff (1s, 2s, 4s, ...)
Successful solve Yes, once Store the result; Amazon retries submitted with is_retry=true are not double-billed
CAPTCHA_UNSOLVABLE No Send a clearer image or a fresh challenge

Recommended Client Timeouts

Set HTTP client timeouts above the measured p95 latency from our benchmarks:

Endpoint Median p95 Recommended Timeout
/api/tencent.php 0.17s < 1s 5s
/api/geetest.php 0.4s 0.9s 5s
/api/xcaptcha.php 0.8s < 2s 5s
/api/mtcaptcha.php 2.1s < 5s 10s
/api/process.php (OCR) 1.2s 2.5s 10s
/api/amazon.php 8s 14s 30s

Webhooks / Callbacks

CaptchaKings does not use webhooks. All endpoints are synchronous (or instant-poll for the legacy pair), so your application receives results directly in the HTTP response — no callback URL, signature verification, or retry queue to manage.

Billing Events

Next: Error Handling · Rate Limits · Troubleshooting