Métodos de autenticação de proxy para API CaptchaAI

O CaptchaAI devolveu o token e o site continuou bloqueando o formulário? Na maioria dos casos o CAPTCHA foi resolvido certo — só que a partir de um IP diferente do que carregou a página. Turnstile, Cloudflare Challenge e qualquer sessão vinculada a IP exigem essa correspondência, e a forma de assegurar essa correspondência é passar o mesmo proxy do navegador para dentro da chamada da API. Veja o formato exato de cada método suportado — usuário/senha, SOCKS5 e lista de permissões de IP — e quando usar cada um.

Antes de sair configurando, confirme três coisas:

• Se o tipo de desafio realmente exige IP correspondente (tabela abaixo)
• Se o erro que você está vendo já tem causa e correção conhecidas (referência de erros abaixo)
• Se o proxy escolhido aceita conexões externas — são os servidores da CaptchaAI que se conectam a ele, não o seu servidor

Quando você realmente precisa passar um proxy

Erros comuns e como corrigir

Referência rápida: formato do parâmetro proxy

Como autenticar cada tipo de proxy

1. Usuário e senha (proxy HTTP)

O formato mais comum: credenciais completas dentro do parâmetro proxy, com proxytype definido como 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. Usuário e senha (proxy SOCKS5)

Mesma lógica, só muda o proxytype para SOCKS5 — útil quando o provedor só oferece esse protocolo.

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. Lista de permissões de IP (sem usuário/senha)

Alguns provedores de proxy autenticam por lista de permissões de IP em vez de credenciais:

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")

Importante: para proxies com lista de permissões de IP, você também precisa liberar os IPs dos servidores da CaptchaAI — são eles que se conectam ao seu proxy para resolver o desafio, não o seu servidor.

4. Proxy HTTPS (método CONNECT)

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 ...

Exemplo em Node.js

A mesma lógica de envio e consulta, agora em JavaScript:

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
  }
);

Formatos por provedor de proxy

Mesmo padrão host:port:user:pass em todos — muda só o host e a convenção de usuário:

# 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"

Perguntas frequentes

O que acontece se o proxy falhar durante a resolução?

A CaptchaAI retorna ERROR_PROXY_CONNECTION_FAILED. Implemente retentativa com um proxy substituto antes de escalar para o suporte.

Passar proxy deixa a resolução mais lenta?

Um pouco — a CaptchaAI precisa rotear a chamada pelo proxy antes de resolver. Some de 2 a 5 segundos ao tempo típico, e mais ainda com workers na região sa-east-1 (São Paulo) da AWS chamando um proxy nos Estados Unidos.

Qual é o formato correto do parâmetro proxy?

host:port:user:pass para HTTP, HTTPS, SOCKS4 e SOCKS5 autenticados, ou apenas host:port para proxies com lista de permissões de IP. Formato incorreto gera ERROR_BAD_PARAMETERS.

Preciso colocar o IP da CaptchaAI na lista de permissões do meu proxy?

Sim, se o provedor autentica por lista de permissões de IP. Os servidores da CaptchaAI também se conectam ao seu proxy para resolver o desafio, então o IP deles precisa estar liberado — não só o seu.

Usar proxy consome mais threads do meu plano CaptchaAI?

Não. A cobrança é por thread simultânea, não por proxy nem por solve — do BASIC (US$ 15/mês, 5 threads) ao VIP-3 (US$ 7500/mês, 5000 threads), usar proxy não muda o consumo de threads.

Guias relacionados

• Proxy SOCKS5 na prática com a CaptchaAI
• Como a qualidade do proxy afeta a taxa de resolução
• Bright Data + CaptchaAI: integração de proxy

Configure a autenticação de proxy na API da CaptchaAI e feche a lacuna entre o IP que carrega a página e o IP que resolve o desafio — obtenha sua chave de API.