> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # hCaptcha API di riconoscimento delle immagini > hCaptcha verification code recognition service API guide - Ace Data Cloud 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](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare per uso futuro. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 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](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [hCaptcha API di riconoscimento delle immagini →](https://platform.acedata.cloud/documents/recognition-hcaptcha-integration) ## 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: ```json theme={null} { "solution": { "label": "Please click on the UNIQUE object among the others", "box": [ "360", "276" ], "confidences": 0.6354503631591797 } } ``` 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: ```shell theme={null} 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: ```python theme={null} 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) ``` ## 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: ```shell theme={null} 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"], "async": true }' ``` ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab", "status": "processing" } ``` Successivamente, utilizza il `task_id` per effettuare il polling su `POST /captcha/tasks` (si consiglia ogni 3\~5 secondi) per ottenere i risultati: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/captcha/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002" }' ``` Durante l'elaborazione verrà restituito `status: processing`: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "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): ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "ready", "solution": { "label": "Si prega di fare clic sull'oggetto UNICO tra gli altri", "box": ["360", "276"], "confidences": 0.6354503631591797 } } ``` 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 ```json theme={null} { "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 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.