Reference

CaptchaAI API Quick Reference Card

Python All CAPTCHA Types
By Irina
Published at Mar 05, 2026
CaptchaAI API Quick Reference Card
Featured image unavailable

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

Base URLs

Purpose URL
Submit task https://ocr.captchaai.com/in.php
Get result https://ocr.captchaai.com/res.php
Check balance https://ocr.captchaai.com/res.php?key=KEY&action=getbalance

Authentication

All requests require key=YOUR_API_KEY as a parameter.

Submit Task — Common Parameters

Parameter Required Description
key Yes Your API key
method Yes CAPTCHA type identifier
pageurl Yes* URL of the page with the CAPTCHA
json No Set 1 for JSON responses
soft_id No Developer application ID
proxy No Proxy in type:host:port:user:pass format
proxytype No HTTP, HTTPS, SOCKS4, SOCKS5

*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

Parameter Values Description
numeric 0=any, 1=digits, 2=letters, 3=either, 4=none Character type
regsense 0=insensitive, 1=case-sensitive Case sensitivity
minLen 1-20 Minimum text length
maxLen 1-20 Maximum text length
phrase 0=single word, 1=phrase (spaces) Multi-word answer
calc 0=text, 1=math expression Math CAPTCHA
language 0=any, 1=Cyrillic, 2=Latin Character set
textinstructions text Solving hint

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

Error Code Meaning Action
ERROR_WRONG_USER_KEY Invalid API key format Check key format
ERROR_KEY_DOES_NOT_EXIST API key not found Verify key in dashboard
ERROR_ZERO_BALANCE Insufficient funds Top up account
ERROR_NO_SLOT_AVAILABLE Server busy Retry after 5 seconds
ERROR_CAPTCHA_UNSOLVABLE Cannot solve this CAPTCHA Retry with fresh challenge
ERROR_BAD_DUPLICATES Too many identical failures Check image quality
ERROR_WRONG_CAPTCHA_ID Invalid task ID Submit new task
ERROR_TOO_BIG_CAPTCHA_FILESIZE Image exceeds 100KB Compress or resize
ERROR_IMAGE_TYPE_NOT_SUPPORTED Invalid image format Use PNG, JPG, or GIF
ERROR_PAGEURL Missing or invalid pageurl Provide full URL
ERROR_GOOGLEKEY Missing sitekey Extract sitekey from page

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.

Solve any CAPTCHA in minutes — get your API key.

Discussions (0)

No comments yet.