Errores de coordenadas de imagen de cuadrícula: diagnóstico y solución

Si CaptchaAI te devuelve celdas equivocadas en una cuadrícula de imágenes, casi nunca es un fallo del modelo: el problema suele estar en tres parámetros que tú controlas —el tamaño de la cuadrícula, la imagen que envías y el texto de instrucciones—. Los grid CAPTCHA (los desafíos de imágenes de reCAPTCHA v2) devuelven índices de celda como respuesta, así que cuando esos índices no encajan (haces clic en los mosaicos incorrectos o recibes ERROR_CAPTCHA_UNSOLVABLE), el diagnóstico casi siempre termina en uno de esos tres frentes. Esta guía los recorre de mayor a menor frecuencia.

El escenario típico en el mercado hispanohablante es claro: automatizas el QA de un portal de cita previa o el monitoreo de precios en un marketplace regional y, al subir el volumen, empiezan a caer índices que no cuadran con lo que ves en pantalla. Antes de culpar al servicio, revisa cómo llega la imagen a la API.

Diagnóstico rápido según el síntoma

Localiza tu síntoma en esta tabla y salta directamente a la causa más probable:

Cómo devuelve CaptchaAI las celdas de una cuadrícula

CaptchaAI recibe tu imagen de cuadrícula, analiza cada celda y te devuelve una lista de índices que coinciden con la instrucción. Las celdas se numeran de izquierda a derecha y de arriba a abajo:

3×3 Grid:          4×4 Grid:
1 2 3              1  2  3  4
4 5 6              5  6  7  8
7 8 9              9  10 11 12
                   13 14 15 16

Una respuesta como [1, 3, 6, 9] significa que las celdas 1, 3, 6 y 9 contienen los objetos buscados. Toda la lógica de coordenadas descansa sobre dos reglas:

• La numeración del servidor y la de tu código tienen que apuntar a la misma celda.
• Si esa correspondencia se rompe en cualquier punto, el clic termina en el mosaico de al lado.

Causas frecuentes de coordenadas incorrectas y cómo corregirlas

El grid_size no coincide con la cuadrícula real

Es el origen número uno de las coordenadas erróneas. Si el CAPTCHA es una cuadrícula de 4×4 pero envías grid_size=3x3, toda la numeración se desplaza y se seleccionan los mosaicos equivocados, aunque el análisis de la imagen haya sido correcto.

# WRONG — 4×4 grid sent as 3×3
data = {
    "key": "YOUR_API_KEY",
    "method": "post",
    "grid_size": "3x3",      # Wrong!
    "img_type": "recaptcha",
    "instructions": "traffic lights",
    "json": 1
}

# CORRECT — match the actual grid
data = {
    "key": "YOUR_API_KEY",
    "method": "post",
    "grid_size": "4x4",      # Correct
    "img_type": "recaptcha",
    "instructions": "traffic lights",
    "json": 1
}

Detectar el tamaño de la cuadrícula desde el código:

from PIL import Image

img = Image.open("grid_captcha.png")
width, height = img.size

# reCAPTCHA grids are square. 3×3 tiles are ~100px each, 4×4 tiles are ~75px each
tile_width = width // 3
if width % 4 == 0 and (width // 4) < 100:
    grid_size = "4x4"
else:
    grid_size = "3x3"

print(f"Detected grid size: {grid_size}")

Si ya conoces el tamaño esperado del flujo del sitio, conviértelo en una validación explícita antes de enviar la tarea y detecta el desajuste sin gastar una resolución:

def validate_grid_size(width: int, expected: str) -> str:
    detected = "4x4" if width % 4 == 0 and (width // 4) < 100 else "3x3"
    if detected != expected:
        raise ValueError(f"Grid mismatch: expected {expected}, detected {detected}")
    return detected

Imagen recortada, redimensionada o dentro de una captura

Cuando envías una imagen recortada, escalada o incrustada en una captura de página completa, la alineación de la cuadrícula cambia y las celdas dejan de corresponder con la imagen original. CaptchaAI necesita la imagen del CAPTCHA tal y como se renderizó, sin ediciones.

Estas son las manipulaciones que rompen la alineación con más frecuencia:

• Recortar con márgenes que no cuadran con los bordes de los mosaicos.
• Redimensionar o escalar la captura, lo que altera el tamaño de celda que espera el detector.
• Incrustar el CAPTCHA en una captura de página completa en lugar de aislarlo.

Solución: captura la imagen directamente desde el iframe de reCAPTCHA, no una captura de toda la página.

from selenium import webdriver
from selenium.webdriver.common.by import By

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

# Switch to reCAPTCHA iframe
iframe = driver.find_element(By.CSS_SELECTOR, 'iframe[title*="recaptcha"]')
driver.switch_to.frame(iframe)

# Get the grid image element
grid_img = driver.find_element(By.CSS_SELECTOR, "img.rc-image-tile-wrapper img")
grid_img.screenshot("grid_captcha.png")  # Captures just the grid, not the whole page

Instrucciones vagas o que no coinciden con el desafío

# WRONG — too vague
data["instructions"] = "select images"

# CORRECT — specific instruction from the CAPTCHA
data["instructions"] = "crosswalks"

El texto de instrucciones debe reflejar exactamente lo que pide el CAPTCHA: una instrucción genérica lleva al modelo a marcar celdas que no son las correctas, así que extrae el objeto del propio desafío en lugar de fijarlo a mano, porque cambia en cada carga. Estos son los valores que más aparecen en los retos de reCAPTCHA v2:

• crosswalks (pasos de peatones)
• traffic lights (semáforos)
• cars, buses, motorcycles, bicycles (vehículos)
• fire hydrants (bocas de incendio)
• stairs, bridges, parking meters

El índice de celda empieza en 1, no en 0

CaptchaAI devuelve índices de celda basados en 1. Si tu código trabaja con indexación basada en 0, tienes que restar 1 antes de hacer clic. Esto te afecta si usas:

• Arrays o listas de Python, que empiezan en 0.
• Colecciones de find_elements de Selenium.
• Cualquier bucle que consuma el índice crudo del solver.

Si no restas 1, cada clic caerá una posición más allá de la celda correcta.

import json

# CaptchaAI returns 1-based indices
solution = json.loads(result["request"])  # e.g., [1, 3, 6, 9]

# Convert to 0-based for Selenium click automation
zero_based = [cell - 1 for cell in solution]

# Click grid cells using 0-based index
tiles = driver.find_elements(By.CSS_SELECTOR, ".rc-image-tile-wrapper img")
for idx in zero_based:
    tiles[idx].click()

Formato de imagen no admitido

# WRONG — WebP or BMP
files = {"file": open("grid.webp", "rb")}  # Not supported

# CORRECT — convert to PNG first
from PIL import Image
img = Image.open("grid.webp")
img.save("grid.png", "PNG")
files = {"file": open("grid.png", "rb")}

Cualquier formato distinto de los admitidos devuelve ERROR_WRONG_FILE_EXTENSION, así que conviértelo a PNG antes de enviarlo. CaptchaAI acepta:

• JPG / JPEG
• PNG
• GIF

Árbol de decisión para depurar coordenadas

Cuando las celdas salen mal, recorre estas comprobaciones en orden: la mayoría de los casos se resuelve en el primer o segundo paso.

Grid cells are wrong
    ↓
Is grid_size correct (3x3 or 4x4)? → No → Fix grid_size parameter
    ↓ Yes
Is the image the original CAPTCHA (not cropped)? → No → Capture directly from iframe
    ↓ Yes
Is instruction text specific? → No → Use exact CAPTCHA instruction text
    ↓ Yes
Using 1-based indexing for clicks? → No → Convert solution to 0-based
    ↓ Yes
Image in supported format (JPG/PNG)? → No → Convert image format
    ↓ Yes
Report tiles to CaptchaAI via reportbad

Cuándo usar reportbad para celdas mal resueltas

requests.get("https://ocr.captchaai.com/res.php", params={
    "key": "YOUR_API_KEY",
    "action": "reportbad",
    "id": task_id,
    "json": 1
})

Recurre a reportbad cuando las coordenadas sigan saliendo mal de forma consistente pese a tener bien los parámetros. Antes de enviarlo, descarta que el fallo venga de tu lado:

• El grid_size coincide con la cuadrícula real.
• La imagen es el CAPTCHA original, sin recortar.
• Las instrucciones usan el texto exacto del reto.

Reportar una solución incorrecta alimenta la mejora de precisión de CaptchaAI y puede reembolsar el costo de esa resolución. Guarda el task_id de cada envío para reportar sin fricción cuando detectes un patrón de fallos.

Preguntas frecuentes

¿Cómo detecto si la cuadrícula es de 3×3 o de 4×4?

Mide el ancho de la imagen del mosaico: las cuadrículas de reCAPTCHA son cuadradas, con mosaicos de ~100px en 3×3 y de ~75px en 4×4. Automatiza esa comprobación con Pillow y pásala como grid_size en lugar de fijar un valor a mano.

¿Qué formatos de imagen acepta CaptchaAI para grid CAPTCHA?

JPG, JPEG, PNG y GIF. Si tu captura sale en WebP o BMP, conviértela a PNG antes de enviarla; de lo contrario recibirás ERROR_WRONG_FILE_EXTENSION.

¿El reportbad me devuelve el costo de una resolución fallida?

Puede hacerlo. Reportar una solución incorrecta ayuda a mejorar la precisión del servicio y, en muchos casos, reembolsa el costo de esa resolución concreta, siempre que envíes el id de la tarea afectada.

¿Los índices que devuelve CaptchaAI empiezan en 0 o en 1?

En 1. Si tu automatización trabaja con índices basados en 0 —lo habitual en Python o Selenium—, resta 1 a cada valor antes de hacer clic para no desplazar la selección una celda.

Resuelve tus cuadrículas de imágenes con CaptchaAI

Obtén índices de celda precisos para tus desafíos de imágenes en captchaai.com.

Guías relacionadas

• Cómo resolver grid image CAPTCHA con la API
• Referencia de códigos de error de CaptchaAI
• Optimizar la calidad cuando el CAPTCHA de imagen falla
• Validar solicitudes ante ERROR_BAD_PARAMETERS