Naar inhoud springen

API-documentatie

Drie endpoints, volledige codevoorbeelden in zes talen. Integreer in minder dan 60 seconden met het krachtige solvercluster van Capzy.

Snelstart

stap 1
POST /createTask

Dien het captchatype + siteparameters in. Je krijgt direct een taskId terug.

stap 2
POST /getTaskResult

Poll elke ~1s totdat de status ready is. Het token komt in het solution-object.

stap 3
POST /getBalance

Controleer je resterende tegoed. Mislukte oplossingen worden hier automatisch terugbetaald.

basis-urlhttps://api.capzy.aiauthenticatie via clientKey in de request body

Endpoints

POST/createTaskEen nieuwe taak voor captcha-oplossing aanmaken
verzoek
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
antwoord
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultTaakresultaat pollen
verzoek
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
antwoord
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceAccountsaldo controleren
verzoek
{ "clientKey": "capzy_..." }
antwoord
{ "errorId": 0, "balance": 9.50 }
POST/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.
verzoek
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
antwoord
{ "errorId": 0 }
POST/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.
verzoek
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
antwoord
{ "errorId": 0 }
POST/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.
verzoek
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
antwoord
{ "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.

Taaktypes laden…

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.

Standaard
30 gelijktijdig · 30 req/sec

Elk nieuw account begint hier

Hogere gelijktijdigheid
300+ gelijktijdig · 100+ req/sec

Open een supportticket met je verwachte volume (geen apart prijsniveau, hetzelfde tarief per oplossing)

gelijktijdige taken

Hoeveel 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 limit

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

    Je API-sleutel werd niet herkend.

    oplossingControleer de waarde in Dashboard → API-sleutels. Sleutels beginnen met `capzy_`. Geroteerde sleutels worden direct ongeldig.

    #
  • ERROR_IP_NOT_ALLOWED

    Het 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_BLOCKED

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

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

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

    Het 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_TYPE

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

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

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

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

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

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

    De 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_MAINTENANCE

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

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

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

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

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

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

    #
06

Code-playground

Volledig werkende voorbeelden in elke grote taal. Kopieer, plak je API-sleutel, voer uit.

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)
Voorbeeld van uitvoerGeslaagd (200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

Integreer in minder dan 60 seconden.

$0.10 gratis tegoed bij aanmelding. Geen creditcard nodig.

Haal je gratis API-sleutel →