Vai al contenuto principale
Questo documento introduce una spiegazione per l’integrazione dell’API di riconoscimento delle immagini hCaptcha, che può identificare il contenuto inserito dall’utente e l’immagine del codice captcha hCaptcha, restituendo infine le coordinate delle piccole immagini da cliccare per completare la verifica.

​
Processo di richiesta

Per utilizzare l’API, è necessario prima andare alla pagina corrispondente dell’API di riconoscimento delle immagini hCaptcha per richiedere il servizio corrispondente. Una volta entrati nella pagina, cliccare sul pulsante “Acquire”, come mostrato nell’immagine: Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per registrarsi e accedere. Dopo aver effettuato il login o la registrazione, si verrà riportati automaticamente alla pagina corrente. Alla prima richiesta, verrà offerto un credito gratuito, che consente di utilizzare l’API senza costi.

​
Utilizzo di base

Innanzitutto, è importante comprendere il modo di utilizzo di base, ovvero inserire l’immagine del codice captcha hCaptcha da elaborare per ottenere il risultato elaborato. È necessario semplicemente passare un campo queries, che rappresenta l’immagine del codice captcha hCaptcha. Dobbiamo catturare l’immagine del captcha da un sito web che utilizza hCaptcha, il link del sito di esempio è: https://democaptcha.com/demo-form-eng/hcaptcha.html, cliccando sulla casella di controllo si visualizzerà l’immagine completa del captcha, come mostrato nell’immagine seguente:

Il campo queries è lo screenshot dell’immagine del captcha menzionato sopra, si consiglia che la dimensione dell’immagine non superi i 100kb. È necessario anche catturare l’area indicata dalla freccia rossa nell’immagine sopra e comprimere la dimensione dell’immagine, oltre a convertirla in codifica Base64, come mostrato nell’immagine seguente:

Inoltre, è necessario inserire il parametro di contenuto di riconoscimento relativo all’immagine del captcha question, che supporta la traduzione in cinese e inglese. Si può direttamente passare il contenuto di riconoscimento pertinente. Dall’immagine del sito web sopra, si può vedere che l’input di question dovrebbe essere Please click on the UNIQUE object among the others.. Il contenuto specifico è il seguente:

Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, che includono:
  • accept: il formato della risposta desiderata, qui è impostato su application/json, ovvero formato JSON.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.
Inoltre, abbiamo impostato il corpo della richiesta, che include:
  • queries: elenco delle immagini del captcha codificate in Base64.
  • question: parametro di contenuto di riconoscimento relativo all’immagine del captcha, supporta l’inserimento diretto in cinese e inglese.
Dopo aver selezionato, si può notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Try” è possibile effettuare un test, come mostrato nell’immagine sopra, e abbiamo ottenuto il seguente risultato: 
{
  "solution": {
    "label": "Please click on the UNIQUE object among the others",
    "box": [
      "360",
      "276"
    ],
    "confidences": 0.6354503631591797
  }
}
Il risultato restituito ha diversi campi, descritti come segue:
  • solution, il risultato della verifica dopo l’elaborazione dell’immagine del codice captcha hCaptcha.
    • label, il contenuto riconosciuto dall’immagine del codice captcha hCaptcha.
    • box, le informazioni sulla posizione del risultato del riconoscimento dell’immagine del codice captcha hCaptcha, costituite dalle informazioni sulle coordinate dell’immagine.
    • confidences, il livello di confidenza del riconoscimento del contenuto soddisfatto dall’immagine del codice captcha hCaptcha.
Possiamo vedere che abbiamo ottenuto il risultato della verifica dell’immagine del codice captcha hCaptcha. Dobbiamo solo simulare un clic nell’area corrispondente alle coordinate di posizione box per superare la verifica. Di seguito verrà spiegato come cliccare utilizzando le informazioni di posizione box del risultato. Innanzitutto, si deve stabilire un sistema di coordinate cartesiane per l’immagine del captcha caricata, dove l’origine centrale si trova nell’angolo in basso a sinistra dell’immagine, 360 è la coordinata orizzontale corrispondente, 276 è la coordinata verticale corrispondente. Dobbiamo solo simulare un clic sulle coordinate corrispondenti del captcha, come mostrato nell’immagine seguente:

Inoltre, se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente, ad esempio il codice CURL è il seguente: 
curl -X POST 'https://api.acedata.cloud/captcha/recognition/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "Please click on the UNIQUE object among the others.",
  "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}'
Il codice di integrazione in Python è il seguente: 
import requests

url = "https://api.acedata.cloud/captcha/recognition/hcaptcha"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "question": "Please click on the UNIQUE object among the others.",
    "queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:
  • 400 token_mismatched: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 400 api_not_implemented: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.
  • 429 too_many_requests: Troppe richieste, hai superato il limite di frequenza.
  • 500 api_error: Errore interno del server, qualcosa è andato storto sul server.

​
Esempio di risposta di errore

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusione

Attraverso questo documento, hai appreso come utilizzare l’API di riconoscimento delle immagini hCaptcha per far inserire agli utenti il contenuto da riconoscere e l’immagine del codice captcha hCaptcha, restituendo infine le coordinate delle piccole immagini da cliccare per completare la verifica. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio l’API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.