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 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: API di riconoscimento delle immagini hCaptcha →

​
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 sopra menzionata; 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, possiamo vedere che il question da inserire 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 selezionato, 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 dell’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.
  • started_at, finished_at: il tempo di inizio e di produzione del risultato di questa richiesta, timestamp Unix (secondi, float).
  • elapsed: il tempo totale impiegato per questa elaborazione (secondi).
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, dove l’origine centrale si trova nell’angolo in basso a sinistra dell’immagine; 360 corrisponde alla coordinata orizzontale e 276 alla 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 in seguito a leggere il risultato”, puoi passare async: true nel corpo della richiesta. Passando async: true, l’interfaccia restituirà immediatamente un task_id, senza bloccarsi in attesa:
Se desideri controllare attivamente il progresso, puoi utilizzare il task_id per interrogare POST /captcha/tasks (si consiglia ogni 3~5 secondi). Questa interfaccia non attiverà o accelererà l’elaborazione del compito; anche se non interroghi, perdi la connessione o esci dal client, il server continuerà a elaborare:
Durante l’elaborazione verrà restituito status: processing:
Al termine dell’elaborazione verrà restituito status: ready e il risultato di riconoscimento solution (la struttura dei campi è completamente identica a quella della modalità sincrona):
Spiegazione della fatturazione: nella modalità asincrona, la creazione di un compito e la lettura dello stato “in elaborazione” non comportano costi; il client verrà addebitato una volta al primo successo della lettura dei risultati (coerente con il comportamento attuale e il prezzo della modalità sincrona). Il server progredirà autonomamente nel compito, ma non addebiterà in anticipo solo perché il backend ha completato prima. Se il compito non ha successo entro 120 secondi, verrà terminato con HTTP 504 timeout, senza costi. /captcha/tasks non è responsabile per il progresso del compito.

​
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 codice 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.