Vai al contenuto

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

passaggio 1
POST /createTask

Invia il tipo di captcha e i parametri del sito. Ricevi subito un taskId.

passaggio 2
POST /getTaskResult

Interroga ogni ~1 s finché lo stato non è ready. Il token arriva nell'oggetto solution.

passaggio 3
POST /getBalance

Controlla i crediti rimanenti. Le risoluzioni non riuscite vengono rimborsate automaticamente qui.

url di basehttps://api.capzy.aiautenticazione tramite clientKey nel corpo della richiesta

Endpoint

POST/createTaskCrea un nuovo task di risoluzione captcha
richiesta
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
risposta
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultInterroga il risultato del task
richiesta
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
risposta
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceControlla il saldo dell'account
richiesta
{ "clientKey": "capzy_..." }
risposta
{ "errorId": 0, "balance": 9.50 }
POST/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.
richiesta
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
risposta
{ "errorId": 0 }
POST/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.
richiesta
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
risposta
{ "errorId": 0 }
POST/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.
richiesta
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
risposta
{ "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.

Caricamento dei tipi di task…

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.

Predefinito
30 simultanei · 30 req/sec

Ogni nuovo account parte da qui

Concorrenza superiore
300+ simultanei · 100+ req/sec

Apri un ticket di supporto indicando il volume previsto (nessun livello di prezzo separato, stessa tariffa per risoluzione)

task simultanei

Quanti 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 frequenza

Quante 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_EXIST

    La 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_ALLOWED

    L'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_BLOCKED

    Il 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_PARAMS

    Il 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_SITEKEY

    Il `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_SUPPORTED

    Il `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_TYPE

    Il 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_REQUIRED

    Questo 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_PROXY

    I 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_REFUSED

    Il 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_REACHED

    Hai 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_LIMITED

    Stai 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_AVAILABLE

    La capacità del cluster è temporaneamente satura.

    soluzioneRiprova dopo qualche secondo (è un problema transitorio). Se persiste per minuti, controlla status.capzy.ai.

    #
  • ERROR_SYSTEM_MAINTENANCE

    Capzy è 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_TIMEOUT

    Il 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_UNSOLVABLE

    Il 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_RESULT

    Il 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_INTERNAL

    Errore 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_BALANCE

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

    #
06

Playground del codice

Esempi completi e funzionanti in tutti i principali linguaggi. Copia, incolla la tua chiave API, esegui.

solve.py
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)
Anteprima dell'outputSuccesso (200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

Integra in meno di 60 secondi.

$0.10 di crediti gratuiti alla registrazione. Nessuna carta di credito richiesta.

Ottieni la tua chiave API gratuita →