La plupart des échecs de résolution BLS CAPTCHA se ramènent à trois causes : des paramètres incomplets envoyés à l'API, une extraction d'images qui manque le canvas ou bute sur l'anti-hotlinking, et un décalage entre les index renvoyés et ceux de votre code. Identifiez laquelle vous concerne, et le correctif prend quelques minutes.
BLS repose sur une implémentation maison, très différente d'un reCAPTCHA ou d'un Turnstile : pas de token unique à récupérer, mais une grille d'images à extraire, à envoyer, puis à re-cliquer dans le bon ordre. C'est cette chaîne qui casse, rarement l'API elle-même. Ce guide part de l'erreur que vous voyez pour remonter à sa cause, sur un environnement que vous êtes autorisé à automatiser — un portail visa BLS, par exemple.
Par où commencer : la check-list
Ce parcours isole la cause en moins d'une minute.
| À vérifier | Comment faire |
|---|---|
| L'instruction est-elle bien extraite ? | Affichez le texte de l'instruction et relisez-le |
| Les images sont-elles valides ? | Enregistrez le base64 dans un fichier et ouvrez-le |
| Le nombre d'images est-il bon ? | Comparez les images envoyées et celles affichées |
| L'ordre des images est-il respecté ? | Confirmez que l'ordre DOM suit l'ordre d'affichage |
| Le préfixe base64 est-il retiré ? | Supprimez data:image/...;base64, |
| Le format de la solution ? | Analysez les index en base 1 séparés par des virgules |
| La conversion d'index est-elle faite ? | Retranchez 1 pour l'accès au tableau en base 0 |
Erreurs à la soumission à l'API
ERROR_BAD_PARAMETERS signale qu'un paramètre obligatoire manque : l'instruction ou les images. Envoyez toujours instructions avec vos images.
# WRONG — missing instructions
response = requests.post("https://ocr.captchaai.com/in.php", data={
"key": API_KEY, "method": "bls",
"image_base64_1": img1, "json": 1
})
# CORRECT — include instructions
response = requests.post("https://ocr.captchaai.com/in.php", data={
"key": API_KEY, "method": "bls",
"instructions": "Select all images with a car",
"image_base64_1": img1, "json": 1
})
ERROR_WRONG_FILE_EXTENSION apparaît quand le base64 est invalide ou dans un format non pris en charge. Encodez les images en PNG ou JPEG, retirez le préfixe data:image/...;base64,, et vérifiez que la chaîne n'est pas tronquée.
import base64
# Strip the data URI prefix
src = img_element.get_attribute("src")
if src.startswith("data:image"):
b64 = src.split(",")[1]
else:
# Download and encode
img_data = requests.get(src).content
b64 = base64.b64encode(img_data).decode()
ERROR_CAPTCHA_UNSOLVABLE pointe vers des images trop dégradées ou floues, ou une instruction ambiguë. Capturez les images en pleine résolution, confirmez que le texte de l'instruction est bien extrait, puis relancez : certains défis restent plus difficiles.
Problèmes d'extraction des images
Trois pièges reviennent quand vous récupérez la grille depuis le navigateur.
Les images se chargent dynamiquement et ne sont pas encore dans le DOM au premier affichage : attendez que le captcha soit entièrement rendu avant de lire les éléments.
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
# Wait for captcha images to load
WebDriverWait(driver, 10).until(
EC.presence_of_all_elements_located((By.CSS_SELECTOR, ".captcha-image img"))
)
Certaines implémentations BLS dessinent les images sur des éléments <canvas> plutôt que sur des balises img. Exportez alors le contenu du canvas en base64.
canvas_elements = driver.find_elements(By.CSS_SELECTOR, ".captcha-canvas")
for i, canvas in enumerate(canvas_elements, 1):
b64 = driver.execute_script(
"return arguments[0].toDataURL('image/png').split(',')[1];",
canvas
)
payload[f"image_base64_{i}"] = b64
Enfin, les images protégées contre le hotlinking renvoient un 403 dès qu'elles sont récupérées hors du navigateur. Extrayez-les depuis le contexte du navigateur, comme le ferait la page elle-même.
# Get image data from within the browser
b64 = driver.execute_script("""
var img = arguments[0];
var canvas = document.createElement('canvas');
canvas.width = img.naturalWidth;
canvas.height = img.naturalHeight;
canvas.getContext('2d').drawImage(img, 0, 0);
return canvas.toDataURL('image/png').split(',')[1];
""", img_element)
Erreurs à l'application de la solution
Les mauvaises images sont cliquées lorsque l'ordre diffère entre l'extraction et l'affichage. Indexez toujours dans l'ordre du DOM, qui correspond à l'ordre d'affichage.
# Ensure images are indexed in display order
captcha_imgs = driver.find_elements(By.CSS_SELECTOR, ".captcha-image img")
# The order of find_elements matches DOM order = display order
for i, img in enumerate(captcha_imgs, 1):
payload[f"image_base64_{i}"] = extract_base64(img)
Les index de la solution tombent à côté parce que CaptchaAI renvoie des index en base 1, alors que votre tableau est en base 0. Retranchez systématiquement 1 avant l'accès.
solution = result["request"] # e.g., "1,3,5"
indices = [int(i) for i in solution.split(",")]
# Convert to 0-based for array access
for idx in indices:
captcha_imgs[idx - 1].click() # 1-based → 0-based
Le formulaire échoue malgré une sélection correcte quand un champ ou un jeton caché, attendu par le formulaire, n'est pas envoyé. Repérez ces champs masqués. Sur un portail visa BLS, ils peuvent contenir des données personnelles : limitez ce que vous journalisez (RGPD).
# Look for hidden captcha tokens
hidden_fields = driver.find_elements(By.CSS_SELECTOR, "input[type='hidden']")
for field in hidden_fields:
name = field.get_attribute("name")
value = field.get_attribute("value")
print(f"Hidden field: {name}={value}")
Erreurs de timeout et d'expiration
La fenêtre de validité de BLS CAPTCHA est courte, ce qui est fréquent sur les portails de rendez-vous visa très sollicités. Extrayez les images et envoyez-les à CaptchaAI dans la foulée ; ne les extrayez jamais pour attendre avant de soumettre. Si la résolution dépasse 60 secondes, le captcha a sans doute expiré : rechargez et recommencez.
Si l'interrogation des résultats traîne, vérifiez que vous interrogez le résultat correctement, sans marteler l'endpoint.
# Standard polling pattern
for _ in range(30): # 30 attempts × 5 seconds = 150 seconds max
time.sleep(5)
result = requests.get("https://ocr.captchaai.com/res.php", params={
"key": API_KEY, "action": "get", "id": task_id, "json": 1
}).json()
if result.get("status") == 1:
return result["request"]
if result.get("request") == "ERROR_CAPTCHA_UNSOLVABLE":
# Don't keep polling — start over
raise Exception("Unsolvable")
FAQ
Pourquoi le captcha BLS expire-t-il avant la fin de la résolution ?
Parce que sa fenêtre de validité est courte et que vous avez sûrement inséré une attente entre l'extraction et l'envoi. Extrayez les images et soumettez-les immédiatement ; au-delà de 60 secondes, rechargez le défi.
Comment savoir si l'erreur vient de mon extraction ou de l'API ?
Sauvegardez le base64 que vous envoyez et ouvrez-le comme une image. Illisible ou vide, le problème est en amont, côté extraction ; nette mais refusée avec ERROR_CAPTCHA_UNSOLVABLE, réexaminez l'instruction et le nombre d'images.
Faut-il continuer à interroger après un ERROR_CAPTCHA_UNSOLVABLE ?
Non. Ce statut est définitif pour ce défi : arrêtez le polling, rechargez un nouveau captcha et repartez de zéro. Insister ne fait que gaspiller du temps et un thread.
CaptchaAI accepte-t-il des instructions BLS en français ou en arabe ?
Oui. Envoyez l'instruction exactement telle qu'elle s'affiche, sans la traduire : CaptchaAI prend en charge les consignes multilingues via method=bls.
