hCAPTCHA Image
Aperçu
hCaptcha Image est un type de captcha qui oblige les utilisateurs à identifier et sélectionner des images selon des exigences, cliquer sur des points ou faire glisser des images.
hCaptcha Token est largement utilisé sur de nombreux sites web tels que Cloudflare, Discord, OpenSea et de nombreux autres services pour se protéger contre les bots.

1. Créer une tâche
Requête
POST https://api.achicaptcha.com/createTask
Paramètres
| Nom du paramètre | Type de données | Requis ? | Description |
|---|---|---|---|
clientKey | string | oui | Clé API |
task.type | string | oui | HCaptchaImageTask |
task.subType | string | oui | Valeur égale à 0 |
task.image | string | oui | Liste d'images base64 séparées par |base64_question1|base64_question2|...|base64_question9|base64_sample1|base64_sample2|...|base64_sampleNRemarque : Les images d'échantillon peuvent être présentes ou non. Les images doivent être encodées en base64 |
task.other | string | oui | Question|Nombre d'images|Type de captcha Exemple : "Veuillez identifier et cliquer sur toutes les images représentant un oiseau|9|grid"- Question : "Veuillez identifier et cliquer sur toutes les images représentant un oiseau" - Nombre d'images : 9 (Compter uniquement les images dans la grille question, pas les images sample)- Type de captcha : grid (sélectionner les cellules dans 9 cellules qui répondent à la condition) ou bbox (cliquer sur un/plusieurs points ou faire glisser pour marquer un objet qui répond à la condition) ou drag (faire glisser une/plusieurs pièces de puzzle pour créer une image complète) |
Exemple de requête
POST /createTask HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
{
"clientKey": "VOTRE_CLE_API",
"task": {
"type": "HCaptchaImageTask",
"subType": "0",
"image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|...(9 images base64 jointes par |)",
"other": "Veuillez identifier et cliquer sur toutes les images représentant un oiseau|9|grid"
}
}Réponse
En cas de succès, le serveur renvoie errorId = 0 et taskId
{
"errorId": 0,
"taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}Exemples d'images à envoyer au serveur de résolution de captcha
Astuce : Pour obtenir la meilleure qualité de reconnaissance captcha, rognez votre image comme indiqué par les encadrés rouges et violets dans les exemples ci-dessous.
Assurez-vous que la résolution de l'image recadrée reste d'au moins 500–600 pixels de large/haut pour de meilleurs résultats.

2. Obtenir le résultat
Requête
POST https://api.achicaptcha.com/getTaskResult
Paramètres
| Nom du paramètre | Type de données | Requis ? | Description |
|---|---|---|---|
clientKey | string | oui | Clé API |
taskId | string | oui | TaskId obtenu de (1) |
Exemple de requête
POST /getTaskResult HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
{
"clientKey": "VOTRE_CLE_API",
"taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}Réponse
{
"errorId": 0,
"status": "ready",
// solution: coordonnées des points à cliquer (x1,y1,x2,y2,...)
"solution": "20,30,40,50"
}Explication du statut
errorId = 0etstatus = ready: Résolu avec succès, lire le résultat danssolution.gRecaptchaResponseerrorId = 0etstatus = processing: Résolution du captcha en cours, attendre 2 secondes et réessayererrorId > 0: Erreur système, renvoie le code d'erreur et la description
Exemples d'intégration
import requests
import time
import base64
def image_url_to_base64(url):
"""Convertir l'URL de l'image en base64"""
response = requests.get(url)
return base64.b64encode(response.content).decode('utf-8')
def solve_hcaptcha_image(image_base64_list, question, image_count, captcha_type, api_key='VOTRE_CLE_API'):
# Étape 1 : Créer une tâche
create_task_url = 'https://api.achicaptcha.com/createTask'
create_task_payload = {
'clientKey': api_key,
'task': {
'type': 'HCaptchaImageTask',
'subType': '0',
'image': image_base64_list,
'other': f'{question}|{image_count}|{captcha_type}'
}
}
response = requests.post(create_task_url, json=create_task_payload)
result = response.json()
if result['errorId'] != 0:
raise Exception(result['errorDescription'])
task_id = result['taskId']
# Étape 2 : Obtenir le résultat
get_result_url = 'https://api.achicaptcha.com/getTaskResult'
while True:
time.sleep(2) # Attendre 2 secondes
get_result_payload = {
'clientKey': api_key,
'taskId': task_id
}
response = requests.post(get_result_url, json=get_result_payload)
result = response.json()
if result['errorId'] != 0:
raise Exception(result['errorDescription'])
if result['status'] == 'ready':
return result['solution']['gRecaptchaResponse']
# Si status == 'processing', continuer la boucle
# Utilisation
# Convertir les URL d'images en base64
image_urls = [
'https://example.com/image1.jpg',
'https://example.com/image2.jpg',
# ... autres images
'https://example.com/image9.jpg'
]
base64_images = [image_url_to_base64(url) for url in image_urls]
image_base64_list = '|'.join(base64_images)
question = 'Veuillez identifier et cliquer sur toutes les images représentant un oiseau'
image_count = 9
captcha_type = 'grid' # ou 'bbox'
token = solve_hcaptcha_image(image_base64_list, question, image_count, captcha_type, 'VOTRE_CLE_API')
print('Token hCaptcha:', token)Codes d'erreur courants
| Code d'erreur | Description | Remarques |
|---|---|---|
| 0 | succès | Succès |
| 1 | en traitement | En traitement |
| 2 | champs requis manquants | Champs requis manquants, vérifier à nouveau les paramètres |
| 3 | tâche non prise en charge | Type de tâche non pris en charge |
| 4 | échec de la création de la tâche | Échec de la création de la tâche |
| 5 | la clé client n'existe pas | La clé API n'existe pas, vérifier à nouveau la clé API |
| 6 | solde de compte insuffisant | Solde de compte insuffisant, ajouter plus de crédits |
| 7 | échec de la tâche, veuillez créer une nouvelle tâche | Échec de la tâche, veuillez créer une nouvelle tâche |
| 8 | l'ID de tâche n'existe pas | L'ID de tâche n'existe pas |
Meilleures pratiques
Pour de meilleurs résultats lors de l'utilisation de l'API Achicaptcha, suivez ces principes :
1. Valider les données d'entrée
- Vérifier la liste d'images avant d'envoyer la requête
- Les images doivent être encodées en base64 avant l'envoi
- Assurer le format correct :
base64_image1|base64_image2|...|base64_image9ou avec des images d'échantillon supplémentaires - Vérifier que la question et le type de captcha (grid/bbox) sont exacts
- Le nombre d'images doit correspondre au nombre réel d'images dans la grille
2. Gérer plusieurs tours
- hCaptcha peut nécessiter de résoudre plusieurs tours consécutifs
- L'API Achicaptcha gère automatiquement ces tours
- Le temps de résolution peut être plus long que pour un captcha texte (15-30 secondes)
3. Intervalle d'interrogation
- Attendre au moins 2 secondes entre les vérifications de résultat
- Ne pas spammer l'API avec trop de requêtes consécutives
- Définir un délai d'expiration pour éviter les boucles infinies (recommandé 120 secondes)
4. Logique de nouvelle tentative
- Implémenter une nouvelle tentative pour les erreurs temporaires comme
ERROR_NO_SLOT_AVAILABLE - Utiliser un backoff exponentiel lors de la nouvelle tentative
- Limiter le nombre maximum de tentatives
5. Sécurité de la clé API
- Ne pas coder en dur la clé API dans le code
- Utiliser des variables d'environnement
- Ne pas exposer la clé API côté client
Liens utiles :