Erros e correções comuns de OCR CAPTCHA

O CAPTCHA de imagem voltou com texto errado? Antes de abrir chamado de suporte, confira estas três causas:

• Qualidade da imagem — captcha pequeno, animado ou com fundo transparente prejudica a leitura.
• Parâmetro de dica ausente — numeric, regsense, min_len/max_len ou calc não configurado para o tipo de captcha.
• Formato de envio incorreto — base64 com prefixo data:image/... ou arquivo corrompido no envio.

Este guia mostra como diagnosticar e corrigir cada uma na API da CaptchaAI.

Checklist rápido: parâmetros da API para corrigir a maioria dos erros

Ajuste o parâmetro certo abaixo antes de reenviar a imagem.

Se não resolver, veja o envio ou a imagem abaixo.

Erros ao enviar a imagem para a API

Estes erros acontecem antes da leitura do texto: geralmente é formato, tamanho ou codificação. Os três códigos mais comuns:

• ERROR_WRONG_FILE_EXTENSION — formato ou base64 inválido
• ERROR_ZERO_CAPTCHA_FILESIZE — arquivo vazio
• ERROR_TOO_BIG_CAPTCHA_FILESIZE — arquivo grande demais

ERROR_WRONG_FILE_EXTENSION

• Causa: a imagem não está em um formato aceito ou a string base64 está inválida.
• Correção: valide a codificação antes de enviar, como no exemplo abaixo.

import base64

# Ensure proper encoding
with open("captcha.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

# Don't include the data URI prefix
# WRONG: "data:image/png;base64,iVBOR..."
# RIGHT: "iVBOR..."

ERROR_ZERO_CAPTCHA_FILESIZE

• Causa: o arquivo de imagem chegou vazio ou o download falhou antes do envio.
• Correção: confira o tamanho do arquivo antes de enviar, como no exemplo abaixo.

import os

# Check file size before submitting
if os.path.getsize("captcha.png") == 0:
    print("Image file is empty — re-download")
    # Re-capture the captcha

ERROR_TOO_BIG_CAPTCHA_FILESIZE

• Causa: a imagem ultrapassa o tamanho máximo aceito (normalmente 600 KB).
• Correção: reduza o arquivo antes de enviar, como no exemplo abaixo.

from PIL import Image
import io

img = Image.open("captcha.png")
# Reduce quality without losing text clarity
buffer = io.BytesIO()
img.save(buffer, format="PNG", optimize=True)

Texto errado ou incompleto no retorno

Quando o envio funciona mas a resposta não bate, falta um parâmetro de dica. Os quatro cenários mais comuns:

• Caracteres parecidos trocados entre si (0/O, 1/l/I, 5/S)
• Caixa errada (maiúsculas viram minúsculas)
• Caracteres sobrando ou faltando
• Expressão matemática devolvida sem calcular

Caracteres parecidos trocados entre si

• Causa: o solucionador confunde caracteres visualmente semelhantes (0/O, 1/l/I, 5/S).
• Correção: use os parâmetros de dica para restringir o conjunto de caracteres esperado:

# If captcha is digits only
response = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY, "method": "base64", "body": b64,
    "numeric": 1,  # 1 = digits only
    "json": 1
})

# If captcha is letters only
response = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY, "method": "base64", "body": b64,
    "numeric": 2,  # 2 = letters only
    "json": 1
})

Caixa errada (maiúsculas trocadas por minúsculas)

• Causa: por padrão, o solucionador devolve o texto em minúsculas.
• Correção: ative regsense=1 para preservar a diferenciação entre maiúsculas e minúsculas:

response = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY, "method": "base64", "body": b64,
    "regsense": 1,  # Case-sensitive
    "json": 1
})

Caracteres sobrando ou faltando

• Causa: ruído na imagem é interpretado como caractere, ou dois caracteres colados são lidos como um só.
• Correção: fixe o comprimento mínimo e máximo esperado:

# If you know the CAPTCHA is always 6 characters
response = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY, "method": "base64", "body": b64,
    "min_len": 6,
    "max_len": 6,
    "json": 1
})

Expressão matemática devolvida sem calcular

• Causa: o solucionador lê o texto "3+7" literalmente, em vez de calcular e devolver "10".
• Correção: ative calc=1:

response = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY, "method": "base64", "body": b64,
    "calc": 1,  # Compute the math expression
    "json": 1
})

Qualidade da imagem: a causa mais comum de erro de OCR

Antes de qualquer parâmetro, confirme a imagem — boa parte dos erros "da API" vêm daqui. Três sintomas cobrem quase todos os casos:

• Captcha pequeno demais (menos de 50 px de altura)
• Captcha animado, com o texto visível só em alguns quadros
• Fundo transparente que o OCR não interpreta bem

CAPTCHA muito pequeno

• Problema: imagens com menos de 50 px de altura perdem detalhe dos caracteres.
• Correção: capture no maior tamanho disponível. É comum em pipelines de QA com Selenium ou Playwright headless e viewport reduzido: o script que funciona localmente falha no CI porque o captcha sai menor. Se a página renderizar o captcha pequeno, verifique se existe uma URL de origem em resolução mais alta:

# Check for higher-res version
img_src = captcha_el.get_attribute("src")
# Some sites use ?size=small — try removing or changing the parameter
high_res_src = img_src.replace("size=small", "size=large")

CAPTCHA animado

• Problema: alguns captchas usam GIFs animados em que o texto só aparece em determinados quadros.
• Correção: extraia o quadro certo:

from PIL import Image

gif = Image.open("captcha.gif")
# Extract each frame and find the one with text
for i in range(gif.n_frames):
    gif.seek(i)
    gif.save(f"frame_{i}.png")

CAPTCHA com fundo transparente

• Problema: PNG com fundo transparente pode não ser lido corretamente pelo OCR.
• Correção: adicione um fundo branco antes de enviar:

from PIL import Image

img = Image.open("captcha.png").convert("RGBA")
background = Image.new("RGBA", img.size, (255, 255, 255, 255))
background.paste(img, mask=img)
background.convert("RGB").save("captcha_white_bg.png")

Como reportar uma resposta errada e recuperar o crédito

Se a CaptchaAI devolver o texto errado, siga dois passos:

1. Confirme o task_id retornado no envio original.
2. Envie a chamada reportbad com esse ID.

# Report bad answer
requests.get("https://ocr.captchaai.com/res.php", params={
    "key": API_KEY,
    "action": "reportbad",
    "id": task_id
})

Isso ajuda a aprimorar a precisão do solucionador e costuma devolver o crédito da requisição. Se as capturas de teste tiverem dado real, considere a LGPD antes de guardá-las — prefira staging com dados fictícios.

Perguntas frequentes

Recebo ERROR_WRONG_FILE_EXTENSION mesmo enviando um PNG válido. O que verificar primeiro?

Confira se a string base64 não inclui o prefixo data:image/png;base64, — a API espera receber só o conteúdo já codificado, puro.

Por que meu captcha volta errado por apenas um caractere?

Normalmente é comprimento mal calculado. Configure min_len e max_len quando souber o tamanho exato, e confirme que a imagem não está borrada.

Base64 ou upload de arquivo: qual devo usar na integração?

Os dois têm a mesma taxa de acerto. Base64 é mais prático para uso programático; upload de arquivo se encaixa melhor em formulários multipart.

O reportbad realmente devolve o crédito da requisição?

Quando a resposta é confirmada como incorreta, sim — o crédito costuma ser devolvido e ajuda a treinar o solucionador para esse padrão.

Guias relacionados

• Como resolver CAPTCHA de imagem pela API
• Como funciona a resolução de CAPTCHA de imagem (OCR)
• Referência de códigos de erro da CaptchaAI