Início rápido do CaptchaAI: sua primeira resolução de CAPTCHA em 5 minutos

Em cerca de cinco minutos você terá um token de CAPTCHA resolvido na mão — sem montar navegador, sem infraestrutura e sem teoria. A API da CaptchaAI trabalha com três verbos: você envia o desafio, consulta o resultado e injeta o token na página ou requisição de destino. Se você já integrou algum serviço no estilo 2Captcha, os endpoints (in.php e res.php) são os mesmos, então a migração é praticamente copiar e colar.

O exemplo deste guia usa o Cloudflare Turnstile, mas todo tipo suportado — reCAPTCHA v2/v3, GeeTest v3, imagem/OCR — segue exatamente o mesmo ciclo de quatro passos:

1. Enviar os dados do CAPTCHA para in.php
2. Guardar o ID da tarefa que volta na resposta
3. Consultar res.php a cada 5 segundos até o resultado ficar pronto
4. Injetar o token na página ou requisição de destino

Passo 0: obtenha sua chave de API

1. Crie sua conta em captchaai.com
2. Abra o painel de API
3. Copie a chave de 32 caracteres

Sua conta precisa de threads ativas para enviar tarefas. Se você ainda está avaliando o serviço, fale com o suporte para liberar threads de teste.

Passo 1: envie o desafio CAPTCHA

O exemplo abaixo resolve um Cloudflare Turnstile — um dos tipos mais comuns hoje. Da página alvo você precisa de apenas dois valores:

• sitekey — a chave pública do widget Turnstile (no atributo data-sitekey ou nos parâmetros do script; começa com 0x)
• pageurl — a URL completa onde o widget é carregado

Escolha a linguagem da sua stack; o corpo da requisição é idêntico em todas.

cURL

curl -X POST "https://ocr.captchaai.com/in.php" \
  -d "key=YOUR_API_KEY" \
  -d "method=turnstile" \
  -d "sitekey=0x4AAAAAAAC3DHQFLr1GavNl" \
  -d "pageurl=https://staging.example.com/qa-login" \
  -d "json=1"

Python

import requests

response = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "turnstile",
    "sitekey": "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl": "https://staging.example.com/qa-login",
    "json": 1,
})
print(response.json())

Node.js

const response = await fetch("https://ocr.captchaai.com/in.php", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: "YOUR_API_KEY",
    method: "turnstile",
    sitekey: "0x4AAAAAAAC3DHQFLr1GavNl",
    pageurl: "https://staging.example.com/qa-login",
    json: "1",
  }),
});
console.log(await response.json());

PHP

<?php
$response = file_get_contents("https://ocr.captchaai.com/in.php?" . http_build_query([
    "key"       => "YOUR_API_KEY",
    "method"    => "turnstile",
    "sitekey"   => "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl"   => "https://staging.example.com/qa-login",
    "json"      => 1,
]));
echo $response;

Passo 2: guarde o ID da tarefa

Uma requisição bem-sucedida devolve algo assim:

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

O campo request traz o ID da tarefa — guarde-o, porque é com ele que você busca o resultado no passo seguinte.

Quando status vier como 0, houve um problema, e o código de erro aparece no próprio campo request:

Passo 3: consulte o resultado

Espere 15 segundos antes da primeira consulta e, a partir daí, verifique a cada 5 segundos até o token chegar. Consultar antes disso só devolve CAPCHA_NOT_READY em todas as tentativas e ainda ocupa uma thread à toa.

Python

import time

time.sleep(15)

while True:
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": "YOUR_API_KEY",
        "action": "get",
        "id": "71823469",
        "json": 1,
    }).json()

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

    if result.get("status") == 1:
        token = result["request"]
        print(f"Solved! Token: {token[:60]}...")
        break

    raise RuntimeError(result)

Node.js

await new Promise((r) => setTimeout(r, 15000));

while (true) {
  const r = await fetch(
    `https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=71823469&json=1`,
  );
  const data = await r.json();
  if (data.request === "CAPCHA_NOT_READY") {
    await new Promise((r) => setTimeout(r, 5000));
    continue;
  }
  if (data.status === 1) {
    console.log("Solved:", data.request.slice(0, 60));
    break;
  }
  throw new Error(JSON.stringify(data));
}

Passo 4: injete o token resolvido

A forma de aplicar o token muda conforme o tipo de CAPTCHA:

• Turnstile / reCAPTCHA — escreva o valor no campo cf-turnstile-response ou g-recaptcha-response, ou dispare o callback da página.
• Imagem / OCR — coloque o texto reconhecido no input de resposta.
• GeeTest v3 — preencha os campos retornados (challenge, validate, seccode) conforme o formulário do site.

No navegador, a injeção mínima fica assim:

document.querySelector('[name="cf-turnstile-response"]').value = token;
document.querySelector("form").submit();

Ambiente de teste e uso responsável

Repare que os exemplos usam https://staging.example.com/qa-login de propósito: teste sempre em ambientes que você controla ou tem autorização para automatizar. Se o fluxo envolve coleta ou tratamento de dados de usuários, considere as obrigações da LGPD (ou do RGPD, em Portugal) antes de levar para produção.

Do ponto de vista de latência, a etapa de rede é pequena perto do tempo de resolução. Uma aplicação hospedada em São Paulo (por exemplo, na região sa-east-1) gasta poucos milissegundos no in.php e no res.php, enquanto o Turnstile costuma levar de 15 a 30 segundos para resolver. Dimensione seus timeouts pelo tempo de resolução, não pela rede.

Erros comuns na primeira integração

• Espaço extra ao copiar a chave — remova qualquer espaço no início ou no fim.
• pageurl sem protocolo — a URL precisa começar com https://.
• Primeira consulta cedo demais — aguarde os 15 segundos iniciais.
• Consultas frequentes demais — 5 s já é o suficiente; consultar mais rápido não acelera o resultado.
• Threads esgotadas — confira os códigos de erro da API e o seu plano.

Perguntas frequentes

Quanto custa para começar?

Os planos são cobrados por thread concorrente, não por resolução, e começam no BASIC (US$ 15/mês, 5 threads), com resoluções ilimitadas dentro do mês. Ou seja, você paga pela concorrência que precisa, não por CAPTCHA resolvido. A tabela completa de planos fica na página de preços da CaptchaAI.

Preciso de um navegador para usar a API?

Não. A API funciona só com requisições HTTP: você envia para in.php e consulta res.php. Um navegador com Selenium ou Puppeteer só entra em cena se o token precisar ser injetado em uma página que você está automatizando; para envios diretos por HTTP, ele é dispensável.

O hCaptcha é suportado?

Não. O hCaptcha não é suportado atualmente, assim como o FunCaptcha (Arkose Labs) e o GeeTest v4 (este anunciado como "em breve"). Os tipos cobertos incluem reCAPTCHA v2/v3, Cloudflare Turnstile e Challenge, GeeTest v3, imagem/OCR e grade de imagens, além de CaptchaFox (beta), Friendly Captcha (beta) e Lemin (beta).

Por que a primeira consulta espera 15 segundos?

Porque tipos baseados em token, como Turnstile e reCAPTCHA, levam alguns segundos para serem resolvidos. Consultar em t=0 devolve CAPCHA_NOT_READY em toda tentativa e ainda ocupa uma thread sem necessidade. Espere 15 segundos e, depois, consulte a cada 5.

Posso reaproveitar um token resolvido?

Não. Tokens de Turnstile e reCAPTCHA são de uso único e expiram em cerca de 120 segundos. O ciclo correto é enviar, usar e descartar — nunca faça cache do token.

Próximos passos

• Como resolver reCAPTCHA v2 pela API, passo a passo
• Como resolver o Cloudflare Turnstile pela API
• Como resolver GeeTest v3 pela API
• Resolução de CAPTCHA de imagem pela API