> ## 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.

# Istruzioni per l'integrazione dell'API di riconoscimento delle immagini Recaptcha2

> Recaptcha verification code recognition service API guide - Ace Data Cloud

Questo documento introduce un'API di riconoscimento delle immagini Recaptcha2, che può identificare il contenuto inserito dall'utente e l'immagine del codice captcha Recaptcha2, restituendo infine le coordinate delle piccole immagini da cliccare per completare la verifica.

## Procedura di richiesta

Per utilizzare l'API di riconoscimento delle immagini Recaptcha2, 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: [API di riconoscimento delle immagini Recaptcha2 →](https://platform.acedata.cloud/documents/captcha-recognition-recaptcha2)

## Utilizzo di base

Iniziamo a comprendere il modo di utilizzo di base, dobbiamo catturare l'immagine del codice captcha Recaptcha2 dal sito web; l'URL del sito di esempio è: `https://www.google.com/recaptcha/api2/demo`, la pagina specifica è mostrata nell'immagine qui sotto:

<p>
  <img src="https://cdn.acedata.cloud/3mgkjk.png" width="500" className="m-auto" />
</p>

Dobbiamo cliccare sulla casella di controllo del captcha affinché appaia l'immagine del captcha; nella figura sopra, la freccia gialla indica un testo, questo testo è il valore di `question` di cui si parlerà più avanti. Prima di tutto, è necessario passare un campo `image`, che è l'immagine specifica del captcha Recaptcha2, l'immagine è quella indicata dalla freccia rossa nell'immagine sopra, e deve essere ridimensionata a una dimensione standard (100x100, 300x300, 450x450), in modo che il servizio possa determinare il tipo di immagine; la compressione dell'immagine deve essere effettuata da te, in questo documento si consiglia un [sito di compressione](https://www.photopea.com/), dove puoi ridimensionare e comprimere l'immagine, il risultato compresso è mostrato nell'immagine qui sotto:

![](https://cdn.acedata.cloud/l7aotl.png)

È inoltre necessario inserire il parametro di contenuto di riconoscimento relativo all'immagine del captcha `question`, abbiamo fornito la seguente tabella di contenuti come riferimento:

### Tabella dei contenuti in cinese

```json theme={null}
{
  "/m/0pg52": "出租车",
  "/m/01bjv": "巴士",
  "/m/02yvhj": "校车",
  "/m/04_sv": "摩托车",
  "/m/013xlm": "拖拉机",
  "/m/01jk_4": "烟囱",
  "/m/014xcs": "人行横道",
  "/m/015qff": "红绿灯",
  "/m/0199g": "自行车",
  "/m/015qbp": "停车计价表",
  "/m/0k4j": "汽车",
  "/m/015kr": "桥",
  "/m/019jd": "船",
  "/m/0cdl1": "棕榈树",
  "/m/09d_r": "山",
  "/m/01pns0": "消防栓",
  "/m/01lynh": "楼梯"
}
```

### Tabella dei contenuti in inglese

```json theme={null}
{
  "/m/0pg52": "taxis",
  "/m/01bjv": "bus",
  "/m/02yvhj": "school bus",
  "/m/04_sv": "motorcycles",
  "/m/013xlm": "tractors",
  "/m/01jk_4": "chimneys",
  "/m/014xcs": "crosswalks", // pedestrian crossings è lo stesso
  "/m/015qff": "traffic lights",
  "/m/0199g": "bicycles",
  "/m/015qbp": "parking meters",
  "/m/0k4j": "cars",
  "/m/015kr": "bridges",
  "/m/019jd": "boats",
  "/m/0cdl1": "palm trees",
  "/m/09d_r": "mountains or hills",
  "/m/01pns0": "fire hydrant",
  "/m/01lynh": "stairs"
}
```

Da quanto sopra, possiamo impostare il parametro `question` come corrispondente al id `/m/01pns0` per il id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id del id

```python theme={null}
import requests

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

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

payload = {
    "question": "/m/01pns0",
    "image": "iVBORw0KGgoAAAANSUhEUgAAASoAAAEsCAIAAAD7AWllAAAAAX..."
}

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à elaborato. Se stai facendo un cambio di risolutori multipli (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 bloccare l'attesa:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/recognition/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "/m/01pns0",
  "image": "iVBORw0KGgoAAAANSUhEUgAAASoAAAEsCAIAAAD7AWllAAAAAX...",
  "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 interrogare `POST /captcha/tasks` (si consiglia ogni 3\~5 secondi) per ottenere il risultato:

```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" }
```

Una volta completata l'elaborazione, verrà restituito `status: ready` e il risultato del riconoscimento `solution` (la struttura dei campi è completamente identica a quella della modalità sincrona):

```json theme={null}
{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "solution": {
    "size": 300,
    "label": "/m/01pns0",
    "objects": [2, 5, 7],
    "type": "multi"
  }
}
```

Informazioni di fatturazione: nella modalità asincrona, la creazione di un compito e l'interrogazione "in elaborazione" non comportano costi; **si paga solo una volta quando si ottiene con successo il risultato del riconoscimento** (allo stesso prezzo della modalità sincrona). Pertanto, annullare i compiti non completati durante il cambio non comporterà costi. `/captcha/tasks` è comune a tutte le interfacce di verifica (token e serie di riconoscimento), è possibile interrogare 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 Recaptcha2 per far inserire agli utenti il contenuto riconosciuto e l'immagine del captcha Recaptcha2, restituendo infine le coordinate delle piccole immagini da cliccare per completare la verifica. Speriamo che questo documento ti aiuti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.