API Tutorials

Como resolver CAPTCHA matemático com o parâmetro calc da CaptchaAI

Python Image OCR
Por Equipe CaptchaAI Brasil
Publicado em Jun 20, 2026
Como resolver CAPTCHA matemático com o parâmetro calc da CaptchaAI
Imagem em destaque indisponível

Um CAPTCHA matemático pergunta "8 + 5 = ?" e espera 13, não a equação. Se sua integração devolve "8+5", falta o parâmetro calc: com ele, a CaptchaAI faz a conta e devolve só a resposta, sem você precisar escrever nenhum código de parsing.

Isso importa em qualquer fluxo que valida, envia ou audita respostas automaticamente — de testes de regressão a formulários públicos com verificação anti-spam simples, onde um número pronto é bem mais fácil de comparar do que uma string de equação.

Como funciona o parâmetro calc

Valor de calc O que a API retorna
0 (padrão) O texto da equação como está (por exemplo, "3+7")
1 O resultado já calculado (por exemplo, "10")

Quando vale a pena usar calc=1 (e quando não)

Na prática, a escolha entre deixar a CaptchaAI calcular ou tratar a expressão você mesmo depende do quanto o seu pipeline já confia em parsing local:

  • Formulários com verificação simples (cadastro, newsletter, área de comentários): ative calc=1 e elimine o parsing manual no seu backend.
  • Testes automatizados de QA: comparar um número inteiro simplifica os asserts — sem regex para extrair operandos da string da equação.
  • Pipelines que já têm um parser de expressões robusto: mantenha calc=0 se essa lógica já trata bem parênteses, notação por extenso e casos extremos.
  • Equações fora do padrão (frações, expoentes, texto por extenso): combine calc=1 com textinstructions para orientar a leitura antes de confiar no resultado.

Na dúvida, comece com calc=1 sempre que o layout da equação for previsível. Só volte para o fallback manual se notar erros de leitura consistentes num tipo específico de CAPTCHA.

Enviando a equação para a CaptchaAI resolver

Mesmo padrão de qualquer Image/OCR CAPTCHA: envie a imagem base64 para in.php com calc=1 e numeric=1, guarde o id e consulte res.php. A imagem mostra "3 + 7 = ?" e a função devolve "10" direto:

import requests
import base64
import time
import os

API_KEY = os.environ["CAPTCHAAI_API_KEY"]


def solve_math_captcha(image_b64):
    """Solve a math CAPTCHA — returns the computed result."""
    resp = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY,
        "method": "base64",
        "body": image_b64,
        "calc": 1,          # Compute the math
        "numeric": 1,       # Result will be a number
        "json": 1,
    }, timeout=30)

    result = resp.json()
    if result.get("status") != 1:
        raise RuntimeError(result.get("request"))

    task_id = result["request"]

    time.sleep(8)
    for _ in range(24):
        resp = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY, "action": "get",
            "id": task_id, "json": 1,
        }, timeout=15)
        data = resp.json()
        if data.get("status") == 1:
            return data["request"]
        if data["request"] != "CAPCHA_NOT_READY":
            raise RuntimeError(data["request"])
        time.sleep(5)

    raise TimeoutError("Solve timeout")


# Example: Image shows "3 + 7 = ?"
# With calc=0: Returns "3+7"
# With calc=1: Returns "10"

Formatos de equação que a API reconhece

A CaptchaAI cobre os formatos mais comuns de CAPTCHA matemático, incluindo operações mistas com mais de um sinal na mesma equação:

Format              Example        Result
─────────────────────────────────────────
Addition            3 + 7 = ?      10
Subtraction         15 - 8 = ?     7
Multiplication      4 × 6 = ?      24
Division            20 ÷ 5 = ?     4
Mixed               3 + 4 × 2 = ?  11
Text-based          "three plus five"  8

Times de QA costumam validar esses formatos com dados fictícios em staging.example.com, cobrindo tanto notação numérica quanto frases por extenso antes de liberar a integração em produção.

Instruções de texto para equações fora do padrão

Para parênteses, expoentes ou equação por extenso, inclua textinstructions. Vale também em português: se aparecer "Quanto é sete mais três?", uma instrução como "resolva e responda só com o número" ajuda o solver:

def solve_text_math_captcha(image_b64, instructions):
    """Solve a math CAPTCHA with custom instructions."""
    resp = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY,
        "method": "base64",
        "body": image_b64,
        "calc": 1,
        "textinstructions": instructions,
        "json": 1,
    }, timeout=30)
    return resp.json()


# Example instructions:
# "Solve the math expression and enter the number"
# "What is the result of the equation shown?"
# "Enter the sum of the two numbers"

Tratando respostas fora do padrão

Nem toda resposta chega pronta: pode vir negativa, decimal ou sem a conversão de calc. As funções abaixo normalizam o resultado com um fallback local:

# edge_cases.py


def validate_math_result(answer):
    """Validate and clean math CAPTCHA result."""
    if not answer:
        return None

    # Remove spaces
    answer = answer.strip()

    # Handle negative results
    if answer.startswith("-"):
        try:
            return str(int(answer))
        except ValueError:
            return answer

    # Handle decimal results
    try:
        num = float(answer)
        if num == int(num):
            return str(int(num))
        return str(num)
    except ValueError:
        return answer


def solve_math_with_fallback(image_b64):
    """Try calc=1, fall back to manual parsing if needed."""
    # Try with calc
    result = solve_math_captcha(image_b64)

    # Validate result is actually a number
    try:
        float(result)
        return result
    except (ValueError, TypeError):
        pass

    # Fallback: solve without calc and compute locally
    resp = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY,
        "method": "base64",
        "body": image_b64,
        "calc": 0,      # Get the expression text
        "json": 1,
    }, timeout=30)

    # ... poll for result ...
    expression = "3+7"  # Example OCR result

    # Safely evaluate
    return str(safe_eval(expression))


def safe_eval(expression):
    """Safely evaluate a simple math expression."""
    # Only allow digits and basic operators
    import re
    cleaned = expression.replace("×", "*").replace("÷", "/").replace("=", "").replace("?", "")
    cleaned = cleaned.strip()

    if not re.match(r'^[\d\s+\-*/().]+$', cleaned):
        raise ValueError(f"Unsafe expression: {expression}")

    return eval(cleaned)  # Safe because we validated the pattern

Do clique ao envio: fluxo completo no navegador

Em QA autorizado, com um worker perto da região sa-east-1 da AWS para reduzir latência, o fluxo completo segue cinco passos:

  1. Capture o CAPTCHA como imagem base64 direto do elemento na página.
  2. Envie a imagem para in.php com calc=1 e numeric=1.
  3. Aguarde alguns segundos e consulte res.php até receber o resultado.
  4. Preencha o campo de resposta com o número recebido.
  5. Envie o formulário e trate o erro de validação, se houver.
# full_flow.py
from selenium import webdriver
from selenium.webdriver.common.by import By
import base64
import os


def solve_math_captcha_on_page(driver, captcha_selector, input_selector, submit_selector):
    """Complete flow: capture math CAPTCHA, solve, enter answer."""

    # Capture CAPTCHA image
    captcha_el = driver.find_element(By.CSS_SELECTOR, captcha_selector)
    image_b64 = captcha_el.screenshot_as_base64

    # Solve with calc=1
    answer = solve_math_captcha(image_b64)
    print(f"Math answer: {answer}")

    # Enter the computed result
    input_el = driver.find_element(By.CSS_SELECTOR, input_selector)
    input_el.clear()
    input_el.send_keys(answer)

    # Submit
    driver.find_element(By.CSS_SELECTOR, submit_selector).click()


# Usage
driver = webdriver.Chrome()
driver.get("https://example.com/form")

solve_math_captcha_on_page(
    driver,
    captcha_selector="#captcha-image",
    input_selector="#captcha-answer",
    submit_selector="#submit-btn",
)

Erros comuns e como corrigir

Antes de investigar mais a fundo, confira esses quatro erros mais comuns — a maioria se resolve ajustando um único parâmetro na requisição:

Problema Causa Correção
Retorna a equação em vez do resultado Faltando calc=1 calc=1 na requisição
Resultado errado Operador lido errado (× vs +) textinstructions com o formato
Retorna decimal para equação de inteiros Ponto flutuante str(int(float(result)))
ERROR_CAPTCHA_UNSOLVABLE Equação muito distorcida Pré-processar a imagem

Perguntas frequentes

O que a API devolve se eu não enviar calc?

O texto da equação — "3+7" em vez de 10. Sem calc=1, seu código continua responsável por interpretar operadores e calcular o resultado. Use calc=1 para o resultado pronto.

O calc funciona em qualquer imagem com equação, ou só em layouts específicos?

Funciona em qualquer Image/OCR CAPTCHA com equação legível, sem layout fixo — a CaptchaAI reconhece o padrão pela imagem, não por um template pré-cadastrado.

Como validar o resultado antes de preencher o campo?

Confirme que é numérico com float(resultado) e trate negativos e decimais, como em validate_math_result. Isso evita enviar ao formulário um valor que ainda contenha texto residual da equação.

E se o resultado for negativo?

A CaptchaAI devolve corretamente — "5 - 8 = ?" retorna "-3".

O calc funciona com equações por extenso, como "sete mais três"?

Funciona, com resultado menos previsível. Use textinstructions para melhorar a leitura.

Guias relacionados

Pare de fazer parsing manual — comece com o calc da CaptchaAI.

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