POST /captcha/tasks. Quando chiami qualsiasi interfaccia di verifica (serie token o serie di riconoscimento) passando async: true, l’interfaccia restituirà immediatamente un task_id, il server prenderà immediatamente in carico e continuerà a elaborare; puoi utilizzare quel task_id per interrogare il risultato finale, ma la query non è una condizione per continuare l’esecuzione del compito. Adatto a scenari come il cambio di più risolutori (multi-solver rotation): dopo aver inviato il compito, ottieni immediatamente il task_id, vai a programmare altri risolutori e torna più tardi a leggere i risultati.
📘 Documentazione interattiva completa (incluso il debug online): API di query per i compiti di verifica →
Processo di richiesta
Per utilizzare questa interfaccia, prima vai al Pannello di controllo di Ace Data Cloud per ottenere il tuo API Token, da tenere come riserva. Un API Token è sufficiente per chiamare tutti i servizi della piattaforma, non è necessario richiederne uno per ogni servizio.Utilizzo di base
Primo passo: creare un compito in modo asincrono
Nel corpo della richiesta di qualsiasi interfaccia di verifica, passaasync: true, l’interfaccia restituirà immediatamente un task_id (HTTP 201), senza bloccare l’attesa:
Secondo passo (opzionale): interrogare i risultati con task_id
Se desideri controllare attivamente i progressi, puoi utilizzare iltask_id restituito nel passo precedente per interrogare POST /captcha/tasks (si consiglia ogni 3~5 secondi). Questa interfaccia non attiverà o accelererà l’elaborazione del compito; la lettura dei risultati pronti seguirà il comportamento di regolamento una tantum esistente:
status: processing:
status: ready e il campo risultato corrispondente—la struttura del campo è completamente identica a quella della modalità sincrona:
- serie token (hcaptcha, recaptcha2, recaptcha3) restituisce
token:
- categoria riconoscimento (recognition/recaptcha2, recognition/hcaptcha) restituisce
solution; recognition/image2text restituiscetext.
/captcha/tasks è comune a tutte le interfacce di verifica (serie token e riconoscimento), puoi semplicemente fare polling con lo stesso task_id.
Il server continua a elaborare dall’inizio della creazione, per un massimo di 120 secondi. Se all’ultima query della scadenza non si ottiene ancora un risultato, verrà restituito un HTTP 504 persistente. Questo stato è finale, il client dovrebbe interrompere il polling; ripetere la query dello stesso task_id restituirà stabilmente lo stesso risultato di errore:
status: ready e HTTP 504 includeranno entrambi i campi temporali.
started_at, tempo di inizio dell’elaborazione del compito, timestamp Unix (secondi, float).finished_at, tempo di produzione del risultato del compito, timestamp Unix (secondi, float). Non verrà restituito se è ancora in elaborazione.elapsed, tempo di elaborazione del compito, unità in secondi (float, con 3 cifre decimali). Non verrà restituito se è ancora in elaborazione.
Spiegazione della fatturazione
In modalità asincrona, la creazione di compiti e la lettura dello stato “in elaborazione” non comportano costi; il cliente verrà addebitato una volta al primo successo nella lettura dei risultati (coerente con il comportamento esistente e il prezzo della modalità sincrona). Il server gestirà autonomamente il compito, ma non addebiterà in anticipo se il backend completa prima. I compiti non riusciti entro la scadenza di 120 secondi verranno terminati con HTTP 504 e non comporteranno costi.Gestione degli errori
Quando chiami questa interfaccia, se si verifica un errore, verrà restituito il codice di errore e le informazioni corrispondenti. Ad esempio:400 invalid_request: la richiesta manca del parametrotask_id.401 invalid_token: non autorizzato, il token di autorizzazione è invalido o mancante.404 not_found:task_idnon esiste o non appartiene all’account corrente.504 timeout: il compito è stato terminato e non ha prodotto risultati; si prega di interrompere il polling di queltask_id. Questo errore non comporterà costi.