Skip to content
API
hCAPTCHA
Image

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.

hCaptcha Token BBox

1. Créer une tâche

Requête

POST https://api.achicaptcha.com/createTask

Paramètres

Nom du paramètreType de donnéesRequis ?Description
clientKeystringouiClé API
task.typestringouiHCaptchaImageTask
task.subTypestringouiValeur égale à 0
task.imagestringouiListe d'images base64 séparées par |
base64_question1|base64_question2|...|base64_question9|base64_sample1|base64_sample2|...|base64_sampleN
Remarque : Les images d'échantillon peuvent être présentes ou non. Les images doivent être encodées en base64
task.otherstringouiQuestion|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.

Exemple Multi clic

2. Obtenir le résultat

Requête

POST https://api.achicaptcha.com/getTaskResult

Paramètres

Nom du paramètreType de donnéesRequis ?Description
clientKeystringouiClé API
taskIdstringouiTaskId 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 = 0 et status = ready : Résolu avec succès, lire le résultat dans solution.gRecaptchaResponse
  • errorId = 0 et status = processing : Résolution du captcha en cours, attendre 2 secondes et réessayer
  • errorId > 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'erreurDescriptionRemarques
0succèsSuccès
1en traitementEn traitement
2champs requis manquantsChamps requis manquants, vérifier à nouveau les paramètres
3tâche non prise en chargeType 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
5la clé client n'existe pasLa clé API n'existe pas, vérifier à nouveau la clé API
6solde de compte insuffisantSolde 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
8l'ID de tâche n'existe pasL'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_image9 ou 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 :