Skip to main content
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 di riconoscimento delle immagini hCaptcha, prima di tutto vai al Pannello di controllo di Ace Data Cloud per ottenere il tuo API Token, da conservare per uso futuro. Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ogni servizio. La prima richiesta ti darà un credito gratuito, per un’esperienza senza costi; se il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.
📘 Documentazione completa: hCaptcha API di riconoscimento delle immagini →

​
Utilizzo di base

Iniziamo a comprendere il modo di utilizzo di base, che consiste nell’inserire l’immagine del codice captcha hCaptcha da elaborare, per ottenere il risultato elaborato. Prima di tutto, è necessario passare un campo queries, che rappresenta l’immagine del codice captcha hCaptcha. Dobbiamo catturare questa 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 verrà visualizzata l’immagine completa del captcha, come mostrato nell’immagine sottostante:

Il campo queries è uno screenshot dell’immagine del captcha menzionata 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 dovrai comprimere la dimensione dell’immagine e convertirla in codifica Base64, come mostrato nell’immagine sottostante:

Inoltre, è necessario inserire il parametro di contenuto di riconoscimento relativo all’immagine del captcha question, che supporta la traduzione in cinese e inglese; puoi inserire direttamente il contenuto di riconoscimento pertinente. Dall’immagine del sito web sopra, l’input per 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 di risposta desiderato; 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: un elenco di immagini del captcha codificate in Base64.
  • question: il parametro di contenuto di riconoscimento relativo all’immagine del captcha, che supporta l’inserimento diretto in cinese e inglese.
Dopo aver effettuato la selezione, puoi notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Try” puoi effettuare un test; come mostrato nell’immagine sopra, abbiamo ottenuto il seguente risultato:
Il risultato restituito contiene diversi campi, descritti di seguito:
  • 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 coordinate dell’immagine.
    • confidences, il livello di confidenza del riconoscimento del contenuto dell’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. Prima di tutto, dobbiamo stabilire un sistema di coordinate cartesiane per l’immagine del captcha caricata, con l’origine al centro nell’angolo in basso a sinistra dell’immagine; 360 è la coordinata orizzontale e 276 è la coordinata verticale. Dobbiamo semplicemente simulare un clic sulle coordinate corrispondenti del captcha, come mostrato nell’immagine sottostante:

Inoltre, se desideri generare il codice di integrazione corrispondente, puoi semplicemente copiarlo, ad esempio il codice CURL è il seguente:
Il codice di integrazione in Python è il seguente:

​
Modalità asincrona (async)

Per impostazione predefinita, l’API è sincrona e bloccante: una richiesta attenderà fino a quando il risultato del riconoscimento non sarà completato prima di restituire. Se stai effettuando un cambio di più risolutori (multi-solver rotation) e desideri “ricevere immediatamente il task_id dopo aver inviato il compito, per poi programmare altri risolutori e tornare più tardi a prendere il risultato”, puoi passare async: true nel corpo della richiesta. Passando async: true, l’interfaccia restituirà immediatamente un task_id, senza bloccarsi in attesa:
Successivamente, utilizza il task_id per effettuare il polling su POST /captcha/tasks (si consiglia ogni 3~5 secondi) per ottenere i risultati:
Durante l’elaborazione verrà restituito status: processing:
Al termine dell’elaborazione verrà restituito status: ready e il risultato di riconoscimento solution (la struttura del campo è completamente identica a quella della modalità sincrona):
Spiegazione della fatturazione: nella modalità asincrona, la creazione di un’attività e il polling “in elaborazione” non comportano costi; si fattura solo una volta quando si ottiene con successo il risultato di riconoscimento (allo stesso prezzo della modalità sincrona). Pertanto, annullare le attività non completate durante il polling non comporterà costi. /captcha/tasks è comune a tutte le interfacce di verifica captcha (token e serie di riconoscimento), è possibile effettuare il polling con lo stesso task_id.

​
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

​
Conclusione

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