Migrar de NextCaptcha para CaptchaAI: guia completo

Migrar do NextCaptcha para a CaptchaAI muda três camadas: o endpoint, o formato da requisição e a leitura da resposta — a lógica não muda. O NextCaptcha usa uma API JSON (/createTask, /getTaskResult); a CaptchaAI usa in.php/res.php. Se sua automação já roda em workers na região sa-east-1 (São Paulo), vale medir a latência por requisição nos dois provedores antes de migrar o tráfego de produção — os resultados variam conforme ambiente e horário.

Este guia traz o mapeamento exato — endpoints, parâmetros e código em Python e JavaScript — para migrar sem quebrar a integração em produção.

Checklist rápido de migração

Antes de mexer no código, separe o que precisa mudar:

• ☐ Crie uma conta CaptchaAI e adicione fundos
• ☐ Mapeie os tipos createTask para métodos CaptchaAI
• ☐ Substitua clientKey pela chave de API CaptchaAI
• ☐ Atualize o envio de JSON POST para formulário POST
• ☐ Atualize o polling de POST para GET com parâmetros
• ☐ Atualize a leitura da resposta (status/request)
• ☐ Rode um teste comparativo em paralelo
• ☐ Migre o tráfego de produção aos poucos

Endpoints: o que muda entre NextCaptcha e CaptchaAI

Os endpoints equivalentes:

Como muda o corpo da requisição

O corpo JSON aninhado do NextCaptcha vira parâmetros de formulário simples na CaptchaAI.

Como o NextCaptcha envia a tarefa (JSON)

{
  "clientKey": "next_captcha_key",
  "task": {
    "type": "RecaptchaV2TaskProxyless",
    "websiteURL": "https://example.com",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}

Como a CaptchaAI recebe a mesma tarefa (form-urlencoded)

POST https://ocr.captchaai.com/in.php
key=YOUR_API_KEY&method=userrecaptcha&googlekey=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&pageurl=https://example.com&json=1

Tradução de parâmetros, campo a campo

Equivalência campo a campo:

Qual method da CaptchaAI substitui cada task.type

A CaptchaAI ainda não suporta hCaptcha nem FunCaptcha. Mantenha essas tarefas no provedor atual; migre primeiro reCAPTCHA, Turnstile e imagem.

O que muda na resposta da API

A leitura da resposta muda tanto quanto o envio:

Resposta do envio

Resposta do polling

Migrando o código: Python e JavaScript

Python: como era com o NextCaptcha

import requests
import time

CLIENT_KEY = "your_nextcaptcha_key"
BASE_URL = "https://api.nextcaptcha.com"

def solve_recaptcha_v2(sitekey, pageurl):
    # Submit
    resp = requests.post(f"{BASE_URL}/createTask", json={
        "clientKey": CLIENT_KEY,
        "task": {
            "type": "RecaptchaV2TaskProxyless",
            "websiteURL": pageurl,
            "websiteKey": sitekey
        }
    })
    data = resp.json()
    if data.get("errorId") != 0:
        return {"error": data.get("errorDescription")}

    task_id = data["taskId"]

    # Poll
    for _ in range(60):
        time.sleep(5)
        result = requests.post(f"{BASE_URL}/getTaskResult", json={
            "clientKey": CLIENT_KEY,
            "taskId": task_id
        }).json()
        if result.get("status") == "ready":
            return {"solution": result["solution"]["gRecaptchaResponse"]}
        if result.get("errorId") != 0:
            return {"error": result.get("errorDescription")}

    return {"error": "TIMEOUT"}

Python: como fica com a CaptchaAI

import os
import time
import requests

API_KEY = os.environ["CAPTCHAAI_API_KEY"]

def solve_recaptcha_v2(sitekey, pageurl):
    # Submit — different endpoint and format
    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"]

    # Poll — GET instead of POST, different response format
    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: como era com o NextCaptcha

const axios = require("axios");
const CLIENT_KEY = "your_nextcaptcha_key";
const BASE_URL = "https://api.nextcaptcha.com";

async function solveRecaptchaV2(sitekey, pageurl) {
  const submit = await axios.post(`${BASE_URL}/createTask`, {
    clientKey: CLIENT_KEY,
    task: {
      type: "RecaptchaV2TaskProxyless",
      websiteURL: pageurl,
      websiteKey: sitekey,
    },
  });
  if (submit.data.errorId !== 0) return { error: submit.data.errorDescription };

  const taskId = submit.data.taskId;

  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, 5000));
    const poll = await axios.post(`${BASE_URL}/getTaskResult`, {
      clientKey: CLIENT_KEY,
      taskId,
    });
    if (poll.data.status === "ready") return { solution: poll.data.solution.gRecaptchaResponse };
    if (poll.data.errorId !== 0) return { error: poll.data.errorDescription };
  }
  return { error: "TIMEOUT" };
}

JavaScript: como fica com a CaptchaAI

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

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

  const captchaId = submit.data.request;

  for (let i = 0; i < 60; 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" };
}

Erros comuns na migração

• ERROR_KEY_DOES_NOT_EXIST — uso da clientKey do NextCaptcha; substitua pela chave de API da CaptchaAI.
• Leitura da resposta quebra — estrutura JSON diferente; verifique status (inteiro) e request.
• ERROR_WRONG_USER_KEY — chave malformada; confira o formato no painel da CaptchaAI.
• Tipo de tarefa não reconhecido — nome de tipo do NextCaptcha; mapeie para o method correto (tabela acima).

Perguntas frequentes

Quanto tempo leva para migrar do NextCaptcha para a CaptchaAI?

Para um reCAPTCHA v2 simples, algumas horas — trocar o endpoint, o envio e a leitura de status/request. Com vários tipos de tarefa, conte de um a três dias.

Preciso migrar tudo para formulário, ou a CaptchaAI aceita continuar recebendo JSON?

A CaptchaAI aceita application/x-www-form-urlencoded e JSON no in.php. Pode manter o corpo em JSON na transição; o polling já usa GET simples.

Como ficam as tarefas com proxy depois da migração?

No NextCaptcha, proxy é um tipo separado (RecaptchaV2Task). Na CaptchaAI vira parâmetro: proxy=user:pass@host:port e proxytype=HTTP no mesmo method.

O que muda na cobrança ao trocar de provedor?

A CaptchaAI cobra por thread simultânea, não por tarefa — solves ilimitados por thread. O BASIC (US$ 15/mês, 5 threads) cobre a maioria dos testes; volumes maiores sobem para ADVANCE, PREMIUM ou VIP.

Depois da migração

Valide o teste em paralelo, direcione a produção para a CaptchaAI e desative o NextCaptcha. Crie sua conta e migre em minutos.

Guias relacionados:

• Referência de mapeamento de endpoints entre APIs de CAPTCHA
• Migrando do AZCaptcha para a CaptchaAI
• Migrando do EndCaptcha para a CaptchaAI