API-documentatie
Drie endpoints, volledige codevoorbeelden in zes talen. Integreer in minder dan 60 seconden met het krachtige solvercluster van Capzy.
Snelstart
POST /createTaskDien het captchatype + siteparameters in. Je krijgt direct een taskId terug.
POST /getTaskResultPoll elke ~1s totdat de status ready is. Het token komt in het solution-object.
POST /getBalanceControleer je resterende tegoed. Mislukte oplossingen worden hier automatisch terugbetaald.
https://api.capzy.aiauthenticatie via clientKey in de request bodyEndpoints
/createTaskEen nieuwe taak voor captcha-oplossing aanmaken{
"clientKey": "capzy_...",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAA..."
}
}{
"errorId": 0,
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"status": "processing"
}/getTaskResultTaakresultaat pollen{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.eyJhbGci..."
}
}/getBalanceAccountsaldo controleren{ "clientKey": "capzy_..." }{ "errorId": 0, "balance": 9.50 }/reportScoreOptioneel: rapporteer de geverifieerde score van Google terug voor V3-taken. Voedt de V3-kwaliteitsweergave in je dashboard. Eén rapport per taak; rapporten moeten binnen 24 uur na het voltooien van de oplossing binnenkomen.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"score": 0.9,
"action": "login",
"hostname": "example.com"
}{ "errorId": 0 }/reportCorrectCaptchaOptioneel: laat ons weten dat de oplossing door de doelsite is GEACCEPTEERD. Vooral nuttig voor types die coördinaten teruggeven (bijv. de Shopee-slider), waarbij wij een positie teruggeven en je eigen browser het slepen uitvoert. Dit rapport is ons enige signaal voor nauwkeurigheid in de praktijk. Eén rapport per taak, binnen 24 uur; heeft nooit invloed op de prijs.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }/reportIncorrectCaptchaOptioneel: laat ons weten dat de oplossing door de doelsite is GEWEIGERD. Voedt dezelfde tracking van nauwkeurigheid in de praktijk als /reportCorrectCaptcha. Eén rapport per taak, binnen 24 uur; heeft nooit invloed op de prijs.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }Ondersteunde taaktypes
Laden…Live lijst van de momenteel ingeschakelde taaktypes, gegroepeerd per captchaprovider. Prijzen en gemiddelde oplostijd worden automatisch bijgewerkt op basis van clustertelemetrie.
Rate limits
Limieten gelden per account, opgeteld over alle API-sleutels die je bezit. Boven de limiet krijg je een foutcode zonder dat er tegoed wordt verbruikt.
Elk nieuw account begint hier
Open een supportticket met je verwachte volume (geen apart prijsniveau, hetzelfde tarief per oplossing)
gelijktijdige takenHoeveel taken je tegelijk in de oploswachtrij kunt hebben. Een taak telt mee voor je limiet vanaf createTask totdat hij klaar is (geslaagd, mislukt of time-out).
rate limitHoeveel createTask-calls je per seconde kunt doen. Glijdend venster, per account toegepast. Bij overschrijding krijg je ERROR_RATE_LIMITED en wordt er geen tegoed afgeschreven.
Foutcodes
Elke fout die /createTask / /getTaskResult teruggeeft, met de oplossing. Mislukte oplossingen worden automatisch terugbetaald: het tegoed komt direct terug op je saldo.
Authenticatie
Problemen met je API-sleutel of IP.- #
ERROR_KEY_DOES_NOT_EXISTJe API-sleutel werd niet herkend.
oplossingControleer de waarde in Dashboard → API-sleutels. Sleutels beginnen met `capzy_`. Geroteerde sleutels worden direct ongeldig.
- #
ERROR_IP_NOT_ALLOWEDHet IP van je verzoek staat niet op de allowlist van de API-sleutel.
oplossingVoeg je IP toe aan de allowlist van de sleutel in Dashboard → API-sleutels, of verwijder de allowlist helemaal als je geen IP-pinning nodig hebt.
- #
ERROR_IP_BLOCKEDJe IP is tijdelijk geblokkeerd omdat het te veel ongeldige verzoeken heeft verstuurd.
oplossingWe blokkeren IP's die 100+ ongeldige verzoeken in 10 minuten versturen (oplopend). Los de bug op die de ongeldige verzoeken veroorzaakt en wacht. Blokkades verlopen automatisch na 1 minuut tot 24 uur, afhankelijk van het niveau.
Validatie
Ongeldige taakparameters of verkeerd type voor de sitekey.- #
ERROR_INVALID_PARAMSDe request body was ongeldig of verplichte velden ontbraken.
oplossingControleer of `clientKey` op het hoogste niveau staat en `task` het `type` bevat plus de verplichte identifier (websiteURL/websiteKey/captchaId/enz.). Zie het onderdeel Taaktypes voor de verplichte params per type.
- #
ERROR_BAD_SITEKEYDe `websiteKey` is niet geregistreerd bij een captchaprovider die we kunnen herkennen.
oplossingZorg dat je de volledige sitekey van de doelpagina kopieert (zoek naar `data-sitekey`, `sitekey:` of de parameter in `grecaptcha.render` / `hcaptcha.render`).
- #
ERROR_TASK_NOT_SUPPORTEDHet ingediende `type` van de taak is geen captchatype dat Capzy momenteel ondersteunt.
oplossingZie het onderdeel Taaktypes hieronder voor de volledige lijst van ingeschakelde types. Heb je een captcha nodig die er niet tussen staat, open dan een ticket en we geven hem prioriteit.
- #
ERROR_WRONG_TASK_TYPEHet taaktype komt niet overeen met de werkelijke provider van de sitekey.
oplossingWe controleren sitekeys vooraf bij hun echte provider. Het foutantwoord bevat een veld `recommended`: stap over op dat taaktype. (Er wordt geen tegoed afgeschreven.)
- #
ERROR_PROXY_REQUIREDDeze captcha is IP-gebonden: de tokens zijn gekoppeld aan het IP dat ze heeft opgelost.
oplossingStap over op de `*Task`-variant (in plaats van `*TaskProxyLess`) en geef een `proxyAddress` mee dat overeenkomt met het IP waarmee je het token indient. Geldt voor: Cloudflare Challenge, CaptchaFox, AWS WAF, DataDome, PerimeterX, Kasada, Akamai, Imperva.
- #
ERROR_NO_PROXYProxyvelden zijn verplicht voor dit taaktype maar ontbraken.
oplossingNeem `proxyType`, `proxyAddress`, `proxyPort` (en optioneel `proxyLogin`/`proxyPassword`/`userAgent`) op in de body van je taak.
- #
ERROR_PROXY_CONNECT_REFUSEDDe door jou opgegeven proxy weigerde de verbinding.
oplossingControleer de proxygegevens, de bereikbaarheid van de host en of het IP actief is. Probeer dezelfde proxy eerst vanaf je eigen machine om problemen bij de provider uit te sluiten.
Rate limits
Limieten voor gelijktijdigheid / per seconde / terugbetalingsratio.- #
ERROR_MAX_TASKS_REACHEDJe hebt het maximum aantal gelijktijdige taken voor je accountniveau bereikt.
oplossingWacht tot lopende taken klaar zijn voordat je er meer indient. Het standaardniveau Regular staat 30 gelijktijdige taken toe; neem contact op met support om te upgraden.
- #
ERROR_RATE_LIMITEDJe dient /createTask sneller in dan je rate limit toestaat.
oplossingVertraag en probeer het opnieuw. Het standaardniveau Regular is 30 req/sec in een glijdend venster. Overschrijding van de rate kost geen tegoed.
- #
ERROR_NO_SLOT_AVAILABLEDe clustercapaciteit is tijdelijk verzadigd.
oplossingProbeer het na een paar seconden opnieuw (dit is tijdelijk). Houdt het minutenlang aan, kijk dan op status.capzy.ai.
- #
ERROR_SYSTEM_MAINTENANCECapzy is in gepland onderhoud.
oplossingProbeer het na het onderhoudsvenster opnieuw. We kondigen onderhoud vooraf aan op de statuspagina.
Oplosresultaten
Wat de solver heeft teruggegeven. Mislukte oplossingen worden automatisch terugbetaald.- #
ERROR_TIMEOUTDe taak is niet voltooid binnen de time-out voor dit type.
oplossingAutomatisch terugbetaald, geen kosten. De meeste time-outs zijn tijdelijk. Loopt een specifieke captcha steeds in een time-out, open dan een ticket met de taak-UUID.
- #
ERROR_CAPTCHA_UNSOLVABLEDe solver heeft zijn retrybudget voor deze challenge opgebruikt.
oplossingAutomatisch terugbetaald, geen kosten. Veelvoorkomende oorzaken: verouderde sitekey, websiteURL komt niet overeen met het domein waarin de captcha is ingebed, de captcha is uitgeschakeld door de doelsite.
- #
ERROR_NULL_RESULTDe solver is klaar maar heeft geen token teruggegeven.
oplossingAutomatisch terugbetaald. Meestal betekent dit dat de doelsite de captcha tijdens het oplossen heeft verwijderd. Probeer het opnieuw; houdt het aan, open dan een ticket.
- #
ERROR_INTERNALOnverwachte fout in de oplospipeline.
oplossingAutomatisch terugbetaald. Probeer het opnieuw (dit komt zelden voor). Zie je ze snel achter elkaar, open dan een ticket met de taak-UUID.
- #
ERROR_ZERO_BALANCEHet accountsaldo is te laag om de kosten van de taak te dekken.
oplossingVoeg tegoed toe via Dashboard → Facturering. Mislukte oplossingen worden automatisch terugbetaald, dus je betaalt alleen voor geslaagde tokens.
Scorerapportage
Fouten specifiek voor /reportScore (V3-kwaliteitsfeedback).- #
ERROR_TASK_NOT_FOUND/reportScore: de taskId hoort niet bij je account of is opgeschoond.
oplossingScorerapporten moeten verwijzen naar een taak die van jou was en moeten binnen 24 uur na het voltooien van de oplossing worden ingediend.
- #
ERROR_TASK_NOT_READY/reportScore: de taak wordt nog verwerkt of is al mislukt.
oplossingAlleen taken met status `ready` kunnen een score krijgen. Wacht tot /getTaskResult ready teruggeeft voordat je rapporteert.
- #
ERROR_REPORT_TOO_LATE/reportScore: er is meer dan 24 uur verstreken sinds het voltooien van de oplossing.
oplossingRapporteer scores binnen enkele minuten na je siteverify-call. Dan zijn de gegevens het nuttigst voor ons V3-kwaliteitsdashboard.
Code-playground
Volledig werkende voorbeelden in elke grote taal. Kopieer, plak je API-sleutel, voer uit.
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)Resources
Integreer in minder dan 60 seconden.
$0.10 gratis tegoed bij aanmelding. Geen creditcard nodig.
Haal je gratis API-sleutel →