Reference

Migrar de EndCaptcha para CaptchaAI: Guia de mapeamento de API

Automação Python Todos os tipos de CAPTCHA Migração
Por Equipe CaptchaAI Brasil
Publicado em Jun 21, 2026
Migrar de EndCaptcha para CaptchaAI: Guia de mapeamento de API
Imagem em destaque indisponível

Migrar do EndCaptcha para a CaptchaAI é, na prática, um trabalho de mapeamento: quase toda chamada da API antiga tem um equivalente direto, e o par SOAP/WSDL vira um único POST para in.php seguido de um GET em res.php. Se você já envia imagens e consulta o resultado, a troca é mais uma reescrita de endpoints e parâmetros do que uma mudança de arquitetura.

A diferença de fundo é o protocolo: o EndCaptcha usa SOAP/XML com métodos próprios; a CaptchaAI usa uma API REST autenticada por uma única chave. Este guia traz a equivalência campo a campo, o código em Python e Node.js e um plano de corte sem downtime.

Diferenças de arquitetura entre as duas APIs

Aspecto EndCaptcha CaptchaAI
Protocolo SOAP/XML ou HTTP POST HTTP POST/GET (REST)
Envio /Captcha/Upload ou WSDL https://ocr.captchaai.com/in.php
Resultado /Captcha/GetText ou WSDL https://ocr.captchaai.com/res.php
Autenticação Usuário + senha Chave de API
Resposta XML/personalizado JSON (json=1) ou texto simples

A maior simplificação é abandonar o WSDL: em vez de clientes SOAP e envelopes XML, são duas requisições HTTP comuns — enviar a tarefa e buscar o resultado.

De parâmetros do EndCaptcha para parâmetros da CaptchaAI

O dicionário de campos é quase um de-para direto:

  • username → key: uma única chave de API.
  • password → (removido): a chave já autentica.
  • captchaData (base64) → body (base64): mesmos dados de imagem.
  • captchaType → method: identificadores de tipo diferentes.
  • siteKey → googlekey, pageUrl → pageurl: para reCAPTCHA.
  • captchaId → id: o ID da tarefa no polling.

Tipos de CAPTCHA e o método equivalente

O captchaType numérico vira uma string method legível:

  • Imagem / OCR — method=base64, com body={imagem_base64}.
  • reCAPTCHA v2 — method=userrecaptcha, com googlekey e pageurl.
  • reCAPTCHA v3 — method=userrecaptcha, com googlekey, pageurl, version=v3 e action.

Atenção antes de mapear às cegas: a CaptchaAI cobre reCAPTCHA v2/v3, Cloudflare Turnstile e Challenge, GeeTest v3 e CAPTCHAs de imagem/OCR e grade, mas não resolve hCaptcha atualmente — esse tipo precisa de um plano à parte.

Migrando o código: antes e depois

Python — antes (EndCaptcha)

import requests

USERNAME = "your_endcaptcha_user"
PASSWORD = "your_endcaptcha_pass"

def solve_image_endcaptcha(image_base64):
    # EndCaptcha image solve
    resp = requests.post("https://api.endcaptcha.com/Captcha/Upload", data={
        "username": USERNAME,
        "password": PASSWORD,
        "captchaData": image_base64,
        "captchaType": "1"
    })
    result = resp.json()
    captcha_id = result.get("captchaId")

    import time
    for _ in range(30):
        time.sleep(5)
        poll = requests.post("https://api.endcaptcha.com/Captcha/GetText", data={
            "username": USERNAME,
            "password": PASSWORD,
            "captchaId": captcha_id
        })
        poll_result = poll.json()
        if poll_result.get("text"):
            return {"solution": poll_result["text"]}
        if poll_result.get("error"):
            return {"error": poll_result["error"]}

    return {"error": "TIMEOUT"}

Python — depois (CaptchaAI)

import os
import time
import requests

API_KEY = os.environ["CAPTCHAAI_API_KEY"]

def solve_image_captchaai(image_base64):
    resp = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY,
        "method": "base64",
        "body": image_base64,
        "json": 1
    })
    data = resp.json()
    if data.get("status") != 1:
        return {"error": data.get("request")}

    captcha_id = data["request"]

    for _ in range(30):
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY,
            "action": "get",
            "id": captcha_id,
            "json": 1
        }).json()
        if result.get("status") == 1:
            return {"solution": result["request"]}
        if result.get("request") != "CAPCHA_NOT_READY":
            return {"error": result.get("request")}

    return {"error": "TIMEOUT"}

Duas mudanças de leitura: a autenticação sai do corpo (a key basta) e o resultado vem no campo request, com status marcando o fim. Enquanto a resposta for CAPCHA_NOT_READY, consulte novamente.

Python — reCAPTCHA v2 na CaptchaAI

def solve_recaptcha_v2(sitekey, pageurl):
    resp = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": pageurl,
        "json": 1
    })
    data = resp.json()
    if data.get("status") != 1:
        return {"error": data.get("request")}

    captcha_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY, "action": "get",
            "id": captcha_id, "json": 1
        }).json()
        if result.get("status") == 1:
            return {"solution": result["request"]}
        if result.get("request") != "CAPCHA_NOT_READY":
            return {"error": result.get("request")}

    return {"error": "TIMEOUT"}

JavaScript — antes (EndCaptcha)

const axios = require("axios");

const USERNAME = "your_endcaptcha_user";
const PASSWORD = "your_endcaptcha_pass";

async function solveImageEndCaptcha(imageBase64) {
  const submit = await axios.post("https://api.endcaptcha.com/Captcha/Upload", {
    username: USERNAME,
    password: PASSWORD,
    captchaData: imageBase64,
    captchaType: "1",
  });
  const captchaId = submit.data.captchaId;

  for (let i = 0; i < 30; i++) {
    await new Promise((r) => setTimeout(r, 5000));
    const poll = await axios.post("https://api.endcaptcha.com/Captcha/GetText", {
      username: USERNAME,
      password: PASSWORD,
      captchaId,
    });
    if (poll.data.text) return { solution: poll.data.text };
    if (poll.data.error) return { error: poll.data.error };
  }
  return { error: "TIMEOUT" };
}

JavaScript — depois (CaptchaAI)

const axios = require("axios");
const API_KEY = process.env.CAPTCHAAI_API_KEY;

async function solveImageCaptchaAI(imageBase64) {
  const submit = await axios.post("https://ocr.captchaai.com/in.php", null, {
    params: { key: API_KEY, method: "base64", body: imageBase64, json: 1 },
  });
  if (submit.data.status !== 1) return { error: submit.data.request };

  const captchaId = submit.data.request;

  for (let i = 0; i < 30; i++) {
    await new Promise((r) => setTimeout(r, 5000));
    const poll = await axios.get("https://ocr.captchaai.com/res.php", {
      params: { key: API_KEY, action: "get", id: captchaId, json: 1 },
    });
    if (poll.data.status === 1) return { solution: poll.data.request };
    if (poll.data.request !== "CAPCHA_NOT_READY") return { error: poll.data.request };
  }
  return { error: "TIMEOUT" };
}

Para CAPTCHAs de token, dê mais fôlego ao polling: 60 iterações de 5 s, não 30. No Node.js, os parâmetros vão como query string (params).

Migração sem downtime: rode os dois em paralelo

Não vire a chave de uma vez. Uma equipe em São Paulo com workers em sa-east-1 pode mandar parte do tráfego para a CaptchaAI, comparar taxa de sucesso e tempo de resolução no mesmo ambiente — com dados fictícios e staging — e migrar o restante depois. O corte, em ordem:

  1. Criar a conta e pegar a chave no painel.
  2. Mapear as chamadas do EndCaptcha para os equivalentes.
  3. Trocar a autenticação (usuário/senha → chave de API).
  4. Atualizar envio (/Captcha/Upload → /in.php) e polling (/Captcha/GetText → /res.php).
  5. Ler status e request na resposta.
  6. Rodar os dois provedores em paralelo.
  7. Migrar produção aos poucos e remover as credenciais antigas.

O que muda no dia a dia

  • Autenticação — de usuário + senha para uma única chave de API.
  • Formato de erro — o campo error dá lugar ao campo request padrão.
  • Polling — GET em res.php com parâmetros, não POST a outro endpoint.
  • Verificação de saldo — res.php?action=getbalance&key=KEY, sem método SOAP.
  • Reportar solve incorreto — também um GET: res.php?action=reportbad&id=ID&key=KEY.

Resolução de problemas comuns

  • ERROR_KEY_DOES_NOT_EXIST — você envia o usuário do EndCaptcha; use a chave de API da CaptchaAI.
  • A análise da resposta falha — o JSON mudou; verifique os campos status e request.
  • Parâmetro method ausente — mapeie a numeração captchaType para os métodos da CaptchaAI (base64, userrecaptcha etc.).
  • Timeout no reCAPTCHA — ajuste o polling para 60 iterações de 5 segundos nos CAPTCHAs de token.

Perguntas frequentes

O CaptchaAI resolve os mesmos tipos que eu usava no EndCaptcha?

Depende do tipo. Ela resolve reCAPTCHA v2/v3, Cloudflare Turnstile e Challenge, GeeTest v3 e CAPTCHAs de imagem/OCR e grade. O hCaptcha não é suportado atualmente e precisa de um plano à parte.

Quanto custa a CaptchaAI comparada ao EndCaptcha?

Os planos são por thread, com resolução ilimitada por thread e sem cobrança por solve. A partir do BASIC (US$ 15/mês, 5 threads), o custo depende da concorrência contratada, não do volume resolvido.

Como fica a verificação de saldo depois da migração?

Vira uma chamada GET: res.php?action=getbalance&key=SUA_CHAVE. Sem método SOAP dedicado, fica simples expor o saldo em um painel ou health check.

Artigos relacionados

Próximas etapas

Simplifique a resolução de CAPTCHA com a API REST da CaptchaAI: obtenha sua chave de API e migre hoje.

Guias relacionados:

Os comentários estão desativados para este artigo.