Proxy Authentication Methods for CaptchaAI API

CaptchaAI supports passing your own proxy to the solving API — this makes CaptchaAI solve the CAPTCHA from your proxy's IP, ensuring the token matches the IP that loaded the page. Here's how to configure every authentication method.

When to Pass a Proxy to CaptchaAI

Authentication Methods

1. Username/Password (HTTP)

import requests
import time

CAPTCHAAI_KEY = "YOUR_API_KEY"
CAPTCHAAI_URL = "https://ocr.captchaai.com"


def solve_with_http_proxy(site_url, sitekey, proxy_host, proxy_port,
                           proxy_user, proxy_pass):
    """Pass HTTP proxy to CaptchaAI for IP-matched solving."""
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTP",
        "json": 1,
    })

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

    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY,
            "action": "get",
            "id": task_id,
            "json": 1,
        })
        data = resp.json()
        if data["request"] == "CAPCHA_NOT_READY":
            continue
        if data["status"] == 1:
            return data["request"]
        raise Exception(f"Solve: {data['request']}")

    raise TimeoutError("Timeout")


# Usage
token = solve_with_http_proxy(
    site_url="https://example.com/form",
    sitekey="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    proxy_host="proxy.example.com",
    proxy_port=8080,
    proxy_user="myuser",
    proxy_pass="mypass",
)

2. Username/Password (SOCKS5)

def solve_with_socks5_proxy(site_url, sitekey, proxy_host, proxy_port,
                             proxy_user, proxy_pass):
    """Pass SOCKS5 proxy to CaptchaAI."""
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "SOCKS5",
        "json": 1,
    })

    data = resp.json()
    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY, "action": "get",
            "id": task_id, "json": 1,
        })
        data = resp.json()
        if data["request"] != "CAPCHA_NOT_READY":
            return data["request"]

    raise TimeoutError("Timeout")

3. IP Whitelisting (No Auth)

Some proxy providers authenticate by IP whitelist instead of credentials:

def solve_with_whitelisted_proxy(site_url, sitekey, proxy_host, proxy_port):
    """Proxy with IP whitelist — no username/password."""
    proxy_param = f"{proxy_host}:{proxy_port}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTP",
        "json": 1,
    })

    data = resp.json()
    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY, "action": "get",
            "id": task_id, "json": 1,
        })
        data = resp.json()
        if data["request"] != "CAPCHA_NOT_READY":
            return data["request"]

    raise TimeoutError("Timeout")

Important: For IP whitelist proxies, you must whitelist CaptchaAI's server IPs as well, since CaptchaAI's servers will connect to your proxy.

4. HTTPS (CONNECT) Proxy

def solve_with_https_proxy(site_url, sitekey, proxy_host, proxy_port,
                            proxy_user, proxy_pass):
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTPS",
        "json": 1,
    })

    # ... same polling logic ...

Node.js Examples

const axios = require("axios");

const CAPTCHAAI_KEY = "YOUR_API_KEY";
const API = "https://ocr.captchaai.com";

async function solveWithProxy(siteUrl, sitekey, proxyConfig) {
  const params = {
    key: CAPTCHAAI_KEY,
    method: "userrecaptcha",
    googlekey: sitekey,
    pageurl: siteUrl,
    proxy: `${proxyConfig.host}:${proxyConfig.port}:${proxyConfig.user}:${proxyConfig.pass}`,
    proxytype: proxyConfig.type || "HTTP",
    json: 1,
  };

  const submit = await axios.post(`${API}/in.php`, null, { params });
  const taskId = submit.data.request;

  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, 5000));

    const result = await axios.get(`${API}/res.php`, {
      params: { key: CAPTCHAAI_KEY, action: "get", id: taskId, json: 1 },
    });

    if (result.data.request === "CAPCHA_NOT_READY") continue;
    if (result.data.status === 1) return result.data.request;
  }

  throw new Error("Timeout");
}

// Usage
const token = await solveWithProxy(
  "https://example.com/form",
  "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  {
    host: "proxy.example.com",
    port: 8080,
    user: "myuser",
    pass: "mypass",
    type: "HTTP", // HTTP, HTTPS, SOCKS4, or SOCKS5
  }
);

Proxy Parameter Format Reference

Provider-Specific Formats

# Bright Data
proxy = "brd.superproxy.io:22225:brd-customer-ID-zone-residential:PASSWORD"
proxytype = "HTTP"

# Smartproxy
proxy = "gate.smartproxy.com:10001:spuser:sppassword"
proxytype = "HTTP"

# Oxylabs
proxy = "pr.oxylabs.io:7777:customer-USERNAME:PASSWORD"
proxytype = "HTTP"

Troubleshooting

FAQ

Do I always need to pass a proxy?

No. Most reCAPTCHA v2 implementations don't bind tokens to IPs. Only pass a proxy for IP-bound challenges (Cloudflare, some OAuth flows).

Does passing a proxy slow down solving?

Slightly — CaptchaAI needs to route through your proxy. Add 2-5 seconds to typical solve times.

Can I use rotating proxies with CaptchaAI's proxy parameter?

Use sticky sessions. If you pass a rotating proxy, CaptchaAI might solve from a different IP than the one that loaded the page.

What happens if my proxy fails?

CaptchaAI returns ERROR_PROXY_CONNECTION_FAILED. Implement retry logic with a fallback proxy.

Related Guides

• SOCKS5 Proxy + CaptchaAI
• Proxy Quality Affects Solve Rate
• Bright Data + CaptchaAI

Pass your proxy to CaptchaAI for IP-matched CAPTCHA solving — get your API key.