CaptchaAI API Quick Reference Card

Every endpoint, parameter, and error code in one place.

Base URLs

Authentication

All requests require key=YOUR_API_KEY as a parameter.

Submit Task — Common Parameters

*Not required for image/OCR CAPTCHAs.

Method Reference

reCAPTCHA v2

method=userrecaptcha
googlekey=SITE_KEY
pageurl=PAGE_URL

Optional: invisible=1 for invisible variant.

reCAPTCHA v3

method=userrecaptcha
googlekey=SITE_KEY
pageurl=PAGE_URL
version=v3
action=ACTION_NAME
min_score=0.9

reCAPTCHA Enterprise

method=userrecaptcha
googlekey=SITE_KEY
pageurl=PAGE_URL
enterprise=1

Cloudflare Turnstile

method=turnstile
sitekey=SITE_KEY
pageurl=PAGE_URL

Cloudflare Challenge

method=cloudflare_challenge
sitekey=SITE_KEY
pageurl=PAGE_URL

GeeTest v3

method=geetest
gt=GT_VALUE
challenge=CHALLENGE_VALUE
pageurl=PAGE_URL
api_server=API_SERVER  (optional)

GeeTest v4

method=geetest
gt=CAPTCHA_ID
pageurl=PAGE_URL
version=4

BLS CAPTCHA

method=bls
sitekey=SITE_KEY
pageurl=PAGE_URL
instructions=INSTRUCTIONS  (optional)
code=CODE  (optional)

Image/OCR CAPTCHA (base64)

method=base64
body=BASE64_STRING

Image/OCR CAPTCHA (file upload)

method=post
file=@captcha.png  (multipart)

Image/OCR Optional Parameters

Submit Response

Success

OK|TASK_ID

JSON (json=1):

{"status": 1, "request": "TASK_ID"}

Error

ERROR_KEY_DOES_NOT_EXIST

JSON:

{"status": 0, "request": "ERROR_KEY_DOES_NOT_EXIST"}

Get Result

GET https://ocr.captchaai.com/res.php?key=KEY&action=get&id=TASK_ID

Processing

CAPCHA_NOT_READY

Success

OK|TOKEN_OR_TEXT

Error

ERROR_CAPTCHA_UNSOLVABLE

Error Codes Reference

Polling Best Practices

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://ocr.captchaai.com"

def solve_captcha(submit_params):
    submit_params["key"] = API_KEY
    submit_params["json"] = 1

    resp = requests.post(f"{BASE}/in.php", data=submit_params)
    data = resp.json()

    if data["status"] != 1:
        raise Exception(f"Submit error: {data['request']}")

    task_id = data["request"]

    # Wait before first poll
    time.sleep(10)

    for _ in range(60):
        result = requests.get(
            f"{BASE}/res.php",
            params={"key": API_KEY, "action": "get", "id": task_id, "json": 1}
        ).json()

        if result["request"] == "CAPCHA_NOT_READY":
            time.sleep(5)
            continue

        if result["status"] == 1:
            return result["request"]

        raise Exception(f"Solve error: {result['request']}")

    raise TimeoutError("CAPTCHA solve timed out")

Timing guidelines:

• Initial wait: 10 seconds (20s for reCAPTCHA v3)
• Poll interval: 5 seconds
• Max attempts: 60 (5 minutes total)

Check Balance

balance = requests.get(
    f"{BASE}/res.php",
    params={"key": API_KEY, "action": "getbalance"}
).text
print(f"Balance: ${balance}")

FAQ

What's the maximum image size?

100KB for image/OCR CAPTCHAs. Compress or resize larger images before submitting.

How long do tokens remain valid?

reCAPTCHA: ~120 seconds. Turnstile: ~300 seconds. GeeTest: ~60-120 seconds. Submit tokens immediately after receiving them.

Can I use proxies with all CAPTCHA types?

Proxies are supported for token-based CAPTCHAs (reCAPTCHA, Turnstile, GeeTest). Not applicable for image/OCR.

Related Guides

• CAPTCHA Types Comparison Matrix
• CAPTCHA Glossary

Solve any CAPTCHA in minutes — get your API key.