Documentazione API
Tre endpoint, esempi di codice completi in sei linguaggi. Integra in meno di 60 secondi con il cluster di solver ad alte prestazioni di Capzy.
Guida rapida
POST /createTaskInvia il tipo di captcha e i parametri del sito. Ricevi subito un taskId.
POST /getTaskResultInterroga ogni ~1 s finché lo stato non è ready. Il token arriva nell'oggetto solution.
POST /getBalanceControlla i crediti rimanenti. Le risoluzioni non riuscite vengono rimborsate automaticamente qui.
https://api.capzy.aiautenticazione tramite clientKey nel corpo della richiestaEndpoint
/createTaskCrea un nuovo task di risoluzione captcha{
"clientKey": "capzy_...",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAA..."
}
}{
"errorId": 0,
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"status": "processing"
}/getTaskResultInterroga il risultato del task{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.eyJhbGci..."
}
}/getBalanceControlla il saldo dell'account{ "clientKey": "capzy_..." }{ "errorId": 0, "balance": 9.50 }/reportScoreFacoltativo: segnala il punteggio verificato da Google per i task V3. Alimenta la vista di qualità V3 della tua dashboard. Una segnalazione per task; le segnalazioni devono arrivare entro 24 ore dal completamento della risoluzione.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"score": 0.9,
"action": "login",
"hostname": "example.com"
}{ "errorId": 0 }/reportCorrectCaptchaFacoltativo: comunicaci che la risoluzione è stata ACCETTATA dal sito di destinazione. Particolarmente utile per i tipi che restituiscono coordinate (es. slider di Shopee), dove restituiamo una posizione e il tuo browser esegue il trascinamento. Questa segnalazione è il nostro unico indicatore di precisione nel mondo reale. Una segnalazione per task, entro 24 ore; non influisce mai sui prezzi.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }/reportIncorrectCaptchaFacoltativo: comunicaci che la risoluzione è stata RIFIUTATA dal sito di destinazione. Alimenta lo stesso monitoraggio della precisione reale di /reportCorrectCaptcha. Una segnalazione per task, entro 24 ore; non influisce mai sui prezzi.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }Tipi di task supportati
Caricamento…Elenco in tempo reale dei tipi di task attualmente attivi, raggruppati per provider di captcha. Prezzi e tempo medio di risoluzione si aggiornano automaticamente dalla telemetria del cluster.
Limiti di frequenza
I limiti si applicano per account, aggregati su tutte le chiavi API di tua proprietà. Superare il limite restituisce un codice di errore senza consumare crediti.
Ogni nuovo account parte da qui
Apri un ticket di supporto indicando il volume previsto (nessun livello di prezzo separato, stessa tariffa per risoluzione)
task simultaneiQuanti task puoi avere contemporaneamente nella coda di risoluzione. Un task conta nel tuo limite da createTask fino al suo completamento (successo, errore o timeout).
limite di frequenzaQuante chiamate createTask puoi effettuare al secondo. Finestra mobile, applicata per account. Il superamento del limite restituisce ERROR_RATE_LIMITED senza detrarre crediti.
Codici di errore
Ogni errore restituito da /createTask / /getTaskResult con la relativa soluzione. Le risoluzioni non riuscite vengono rimborsate automaticamente: i crediti tornano subito sul tuo saldo.
Autenticazione
Problemi con la tua chiave API o il tuo IP.- #
ERROR_KEY_DOES_NOT_EXISTLa tua chiave API non è stata riconosciuta.
soluzioneRicontrolla il valore in Dashboard → Chiavi API. Le chiavi iniziano con `capzy_`. Le chiavi ruotate vengono invalidate immediatamente.
- #
ERROR_IP_NOT_ALLOWEDL'IP della tua richiesta non è nella allowlist della chiave API.
soluzioneAggiungi il tuo IP alla allowlist della chiave in Dashboard → Chiavi API, oppure rimuovi completamente la allowlist se non ti serve vincolare l'IP.
- #
ERROR_IP_BLOCKEDIl tuo IP è temporaneamente bannato per aver inviato troppe richieste non valide.
soluzioneBanniamo gli IP che inviano oltre 100 richieste non valide in 10 minuti (con durata crescente). Correggi il bug che causa le richieste non valide, poi attendi. I ban scadono automaticamente da 1 minuto fino a 24 ore a seconda del livello.
Validazione
Parametri del task errati o tipo sbagliato per la sitekey.- #
ERROR_INVALID_PARAMSIl corpo della richiesta era malformato o privo di campi obbligatori.
soluzioneVerifica che `clientKey` sia al livello principale e che `task` contenga `type` più l'identificatore richiesto (websiteURL/websiteKey/captchaId/ecc.). Consulta la sezione Tipi di task per i parametri obbligatori di ciascun tipo.
- #
ERROR_BAD_SITEKEYIl `websiteKey` non è registrato presso alcun provider di captcha che riusciamo a identificare.
soluzioneAssicurati di copiare la sitekey completa dalla pagina di destinazione (cerca `data-sitekey`, `sitekey:` o il parametro in `grecaptcha.render` / `hcaptcha.render`).
- #
ERROR_TASK_NOT_SUPPORTEDIl `type` di task inviato non è un tipo di captcha attualmente supportato da Capzy.
soluzioneConsulta la sezione Tipi di task qui sotto per l'elenco completo di quelli attivi. Se ti serve un captcha non elencato, apri un ticket e gli daremo priorità.
- #
ERROR_WRONG_TASK_TYPEIl tipo di task non corrisponde al provider effettivo della sitekey.
soluzioneVerifichiamo in anticipo le sitekey rispetto al loro provider reale. La risposta di errore include un campo `recommended`: passa a quel tipo di task. (Nessun credito addebitato.)
- #
ERROR_PROXY_REQUIREDQuesto captcha è legato all'IP: i suoi token sono vincolati all'IP che li ha risolti.
soluzionePassa alla variante `*Task` (invece di `*TaskProxyLess`) e passa un `proxyAddress` corrispondente all'IP che userai per inviare il token. Riguarda: Cloudflare Challenge, CaptchaFox, AWS WAF, DataDome, PerimeterX, Kasada, Akamai, Imperva.
- #
ERROR_NO_PROXYI campi del proxy sono obbligatori per questo tipo di task ma erano assenti.
soluzioneIncludi `proxyType`, `proxyAddress`, `proxyPort` (e facoltativamente `proxyLogin`/`proxyPassword`/`userAgent`) nel corpo del task.
- #
ERROR_PROXY_CONNECT_REFUSEDIl proxy che hai fornito ha rifiutato la connessione.
soluzioneControlla le credenziali del proxy, la raggiungibilità dell'host e che l'IP sia attivo. Prova prima lo stesso proxy dalla tua macchina per isolare eventuali problemi del provider.
Limiti di frequenza
Limiti di concorrenza, al secondo e sul rapporto di rimborso.- #
ERROR_MAX_TASKS_REACHEDHai raggiunto il limite di task simultanei per il livello del tuo account.
soluzioneAttendi il completamento dei task in corso prima di inviarne altri. Il livello Regular predefinito prevede 30 task simultanei; contatta il supporto per un upgrade.
- #
ERROR_RATE_LIMITEDStai inviando /createTask più velocemente di quanto consenta il tuo limite di frequenza.
soluzioneRallenta e riprova. Il livello Regular predefinito prevede 30 req/sec con finestra mobile. Il superamento del limite non consuma crediti.
- #
ERROR_NO_SLOT_AVAILABLELa capacità del cluster è temporaneamente satura.
soluzioneRiprova dopo qualche secondo (è un problema transitorio). Se persiste per minuti, controlla status.capzy.ai.
- #
ERROR_SYSTEM_MAINTENANCECapzy è in manutenzione programmata.
soluzioneRiprova al termine della finestra di manutenzione. Pubblichiamo avvisi in anticipo sulla pagina di stato.
Esiti delle risoluzioni
Cosa ha restituito il solver. Le risoluzioni non riuscite vengono rimborsate automaticamente.- #
ERROR_TIMEOUTIl task non è stato completato entro il timeout previsto per il suo tipo.
soluzioneRimborsato automaticamente, nessun addebito. La maggior parte dei timeout è transitoria. Se un captcha specifico va costantemente in timeout, apri un ticket con l'UUID del task.
- #
ERROR_CAPTCHA_UNSOLVABLEIl solver ha esaurito i tentativi disponibili per questa challenge.
soluzioneRimborsato automaticamente, nessun addebito. Cause comuni: sitekey obsoleta, websiteURL non corrispondente al dominio in cui è incorporato, captcha disattivato dal sito di destinazione.
- #
ERROR_NULL_RESULTIl solver ha terminato ma non ha restituito alcun token.
soluzioneRimborsato automaticamente. Di solito indica che il sito di destinazione ha rimosso il captcha durante la risoluzione. Riprova; se persiste, apri un ticket.
- #
ERROR_INTERNALErrore imprevisto nella pipeline di risoluzione.
soluzioneRimborsato automaticamente. Riprova (sono rari). Se li vedi ripetersi in rapida successione, apri un ticket con l'UUID del task.
- #
ERROR_ZERO_BALANCESaldo dell'account insufficiente a coprire il costo del task.
soluzioneAggiungi crediti da Dashboard → Fatturazione. Le risoluzioni non riuscite vengono rimborsate automaticamente, quindi paghi solo i token riusciti.
Segnalazione del punteggio
Errori specifici di /reportScore (feedback sulla qualità V3).- #
ERROR_TASK_NOT_FOUND/reportScore: il taskId non appartiene al tuo account o è stato eliminato.
soluzioneLe segnalazioni di punteggio devono riferirsi a un task di tua proprietà ed essere inviate entro 24 h dal completamento della risoluzione.
- #
ERROR_TASK_NOT_READY/reportScore: il task è ancora in elaborazione o è già fallito.
soluzioneSi possono valutare solo i task `ready`. Attendi che /getTaskResult restituisca ready prima di inviare la segnalazione.
- #
ERROR_REPORT_TOO_LATE/reportScore: sono trascorse più di 24 h dal completamento della risoluzione.
soluzioneSegnala i punteggi entro pochi minuti dalla tua chiamata siteverify. È il momento in cui i dati sono più utili per la nostra dashboard di qualità V3.
Playground del codice
Esempi completi e funzionanti in tutti i principali linguaggi. Copia, incolla la tua chiave API, esegui.
import requests, time
API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"
# Create task
task = requests.post(f"{API}/createTask", json={
"clientKey": KEY,
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAA..."
}
}).json()
task_id = task["taskId"]
# Poll for result
while True:
result = requests.post(f"{API}/getTaskResult", json={
"clientKey": KEY,
"taskId": task_id
}).json()
if result["status"] == "ready":
token = result["solution"]["token"]
print(f"Solved: {token[:50]}...")
break
elif result["status"] == "failed":
print(f"Failed: {result.get('errorDescription')}")
break
time.sleep(1)Integra in meno di 60 secondi.
$0.10 di crediti gratuiti alla registrazione. Nessuna carta di credito richiesta.
Ottieni la tua chiave API gratuita →