Migrar de CapMonster Cloud para CaptchaAI

Trocar de provedor de CAPTCHA parece sinônimo de reescrever a integração inteira — mas não é. A API da CaptchaAI segue o mesmo modelo assíncrono do CapMonster Cloud: enviar, aguardar, consultar. Na maioria dos casos, basta trocar o endpoint e a chave de API. Este guia traz o mapeamento completo de parâmetros, os códigos de erro que mudam de nome e um checklist para não esquecer nenhuma etapa antes de mover o tráfego de produção — com exemplos completos em Python e JavaScript.

O que muda entre CapMonster Cloud e CaptchaAI

Comparação lado a lado, ponto a ponto:

• URL de envio: de https://api.capmonster.cloud/createTask para https://ocr.captchaai.com/in.php
• URL de resultado: de https://api.capmonster.cloud/getTaskResult para https://ocr.captchaai.com/res.php
• Parâmetro da chave de API: de clientKey para key
• Formato da API: de corpo JSON para dados codificados em formulário — a CaptchaAI também aceita JSON, se preferir manter o serializador atual
• Campo do ID da tarefa: de taskId, devolvido na criação, para request, devolvido na resposta de envio
• Campo de resultado: de um objeto solution estruturado para uma string simples em request

Caso comum: uma equipe de QA testando staging.example.com a partir da região sa-east-1 (São Paulo) da AWS. A única variável nova costuma ser a latência até o novo endpoint — meça antes e depois da troca. Se os logs de aplicação guardam tokens de resposta, revise o período de retenção sob a LGPD antes de apontar o ambiente de produção para o novo provedor.

Checklist de migração

Antes de tocar em código, separe o trabalho em duas fases — o que preparar e o que validar durante a troca:

Antes de migrar

• [ ] Obtenha sua chave de API em captchaai.com
• [ ] Troque a URL de envio: api.capmonster.cloud/createTask → ocr.captchaai.com/in.php
• [ ] Troque a URL de resultado: api.capmonster.cloud/getTaskResult → ocr.captchaai.com/res.php
• [ ] Troque a autenticação: clientKey → key

Durante a migração

• [ ] Troque o formato: objeto de tarefa em JSON → parâmetros em formulário
• [ ] Atualize o parsing da resposta: taskId → request, solution.gRecaptchaResponse → request
• [ ] Atualize o tratamento de erro: CAPTCHA_NOT_READY → CAPCHA_NOT_READY
• [ ] Teste uma única resolução antes de migrar o tráfego de produção

Migração rápida: troque duas linhas de código

Se seu código usa um wrapper ou SDK, o caminho mais rápido é trocar a URL base e a chave:

# Before (CapMonster Cloud)
API_URL = "https://api.capmonster.cloud"
CLIENT_KEY = "your_capmonster_key"

# After (CaptchaAI)
SUBMIT_URL = "https://ocr.captchaai.com/in.php"
RESULT_URL = "https://ocr.captchaai.com/res.php"
API_KEY = "your_captchaai_key"

Rode uma única resolução de teste com a nova URL antes de generalizar a troca para todos os workers em produção.

Migração completa do reCAPTCHA v2, passo a passo

Veja o fluxo completo lado a lado:

CapMonster Cloud (antes)

import requests
import time

resp = requests.post("https://api.capmonster.cloud/createTask", json={
    "clientKey": "CAPMONSTER_KEY",
    "task": {
        "type": "RecaptchaV2TaskProxyless",
        "websiteURL": "https://example.com",
        "websiteKey": "6Le-SITEKEY",
    }
}).json()
task_id = resp["taskId"]

while True:
    time.sleep(5)
    result = requests.post("https://api.capmonster.cloud/getTaskResult", json={
        "clientKey": "CAPMONSTER_KEY",
        "taskId": task_id,
    }).json()
    if result["status"] == "ready":
        token = result["solution"]["gRecaptchaResponse"]
        break

CaptchaAI (depois)

import requests
import time

resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "6Le-SITEKEY",
    "pageurl": "https://example.com",
    "json": "1",
}).json()
task_id = resp["request"]

while True:
    time.sleep(5)
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": "YOUR_API_KEY",
        "action": "get",
        "id": task_id,
        "json": "1",
    }).json()
    if result["status"] == 1:
        token = result["request"]
        break
    if result["request"] != "CAPCHA_NOT_READY":
        raise Exception(result["request"])

Mapeamento de parâmetros entre as duas APIs

reCAPTCHA v2

• task.type: "RecaptchaV2TaskProxyless" vira method: "userrecaptcha"
• task.websiteKey vira googlekey
• task.websiteURL vira pageurl
• task.isInvisible: true vira invisible: "1"

Cloudflare Turnstile

• task.type: "TurnstileTaskProxyless" vira method: "turnstile"
• task.websiteKey vira sitekey
• task.websiteURL vira pageurl

Imagem CAPTCHA (OCR)

• task.type: "ImageToTextTask" vira method: "base64"
• task.body continua body, sem mudança

Migrando o código JavaScript/Node.js

O mesmo padrão vale para Node.js:

CapMonster Cloud (antes)

const axios = require('axios');

const resp = await axios.post('https://api.capmonster.cloud/createTask', {
  clientKey: 'CAPMONSTER_KEY',
  task: {
    type: 'RecaptchaV2TaskProxyless',
    websiteURL: 'https://example.com',
    websiteKey: '6Le-SITEKEY',
  }
});
const taskId = resp.data.taskId;

CaptchaAI (depois)

const axios = require('axios');

const resp = await axios.post('https://ocr.captchaai.com/in.php', null, {
  params: {
    key: 'YOUR_API_KEY',
    method: 'userrecaptcha',
    googlekey: '6Le-SITEKEY',
    pageurl: 'https://example.com',
    json: 1,
  }
});
const taskId = resp.data.request;

Como consultar o saldo

A verificação de saldo também muda de endpoint:

CapMonster Cloud

resp = requests.post("https://api.capmonster.cloud/getBalance", json={
    "clientKey": "CAPMONSTER_KEY"
}).json()
balance = resp["balance"]

CaptchaAI

resp = requests.get("https://ocr.captchaai.com/res.php", params={
    "key": "YOUR_API_KEY",
    "action": "getbalance",
    "json": "1",
}).json()
balance = float(resp["request"])

Como mudam os códigos de erro

A maioria dos códigos é idêntica; as exceções ficam na lista abaixo:

• ERROR_KEY_DOES_NOT_EXIST continua ERROR_KEY_DOES_NOT_EXIST
• ERROR_ZERO_BALANCE continua ERROR_ZERO_BALANCE
• ERROR_RECAPTCHA_TIMEOUT vira ERROR_CAPTCHA_UNSOLVABLE
• ERROR_NO_SLOT_AVAILABLE continua ERROR_NO_SLOT_AVAILABLE
• CAPTCHA_NOT_READY vira CAPCHA_NOT_READY

Atenção à grafia: a CaptchaAI retorna CAPCHA_NOT_READY, sem o T de "captcha". Um if que compare a string exata usada pelo CapMonster Cloud falha silenciosamente até alguém notar a diferença nos logs de produção.

Perguntas frequentes

Preciso reescrever toda a lógica de polling?

Não. O conceito é o mesmo: enviar, aguardar, consultar. Só mudam os nomes dos campos, todos convergindo para request.

A CaptchaAI cobre os mesmos tipos de CAPTCHA que eu já uso?

Este guia cobre reCAPTCHA v2, Turnstile e imagem/OCR. hCaptcha e FunCaptcha ainda não são suportados — confirme antes de mover todo o tráfego.

Posso rodar os dois serviços em paralelo durante a transição?

Sim. Direcione parte do tráfego, mantenha o CapMonster Cloud como fallback e migre por completo depois de validar os resultados.

Preciso trocar de plano se o volume for alto?

Depende da concorrência, não do volume. O que determina o plano certo:

• Quantas resoluções simultâneas o seu pico de tráfego exige
• O BASIC (US$ 15/mês, 5 threads) atende testes e volumes baixos
• Resoluções por thread são ilimitadas — para tráfego maior, aumente threads, não o volume contratado

Preciso de um proxy diferente para usar a CaptchaAI?

Não necessariamente. Para reCAPTCHA v2 e Turnstile, as tarefas proxyless resolvem a maioria dos casos sem configuração extra; reserve proxy dedicado para sites com bloqueio agressivo por IP.

Pronto para migrar? Comece agora com a CaptchaAI

Crie sua conta em captchaai.com, troque o endpoint e valide a primeira resposta antes de apontar o tráfego de produção para o novo provedor.

Guias relacionados

Para aprofundar em pontos específicos da migração:

• Mapeamento de endpoint de API: CaptchaAI vs concorrentes
• Comparação de serviços de resolução de CAPTCHA
• Guia de início rápido da API CaptchaAI