Przejdź do treści

Dokumentacja API

Trzy endpointy, pełne przykłady kodu w sześciu językach. Zintegruj się w mniej niż 60 sekund z wydajnym klastrem solverów Capzy.

Szybki start

krok 1
POST /createTask

Prześlij typ captcha i parametry strony. Od razu otrzymasz taskId.

krok 2
POST /getTaskResult

Odpytuj co ~1 s, aż status będzie ready. Token pojawi się w obiekcie solution.

krok 3
POST /getBalance

Sprawdź pozostałe kredyty. Nieudane rozwiązania są tu automatycznie zwracane.

bazowy urlhttps://api.capzy.aiuwierzytelnianie przez clientKey w treści żądania

Endpointy

POST/createTaskUtwórz nowe zadanie rozwiązania captcha
żądanie
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
odpowiedź
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultOdpytaj o wynik zadania
żądanie
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
odpowiedź
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceSprawdź saldo konta
żądanie
{ "clientKey": "capzy_..." }
odpowiedź
{ "errorId": 0, "balance": 9.50 }
POST/reportScoreOpcjonalnie: zgłoś zweryfikowany przez Google wynik dla zadań V3. Zasila widok jakości V3 w Twoim panelu. Jeden raport na zadanie, raporty muszą dotrzeć w ciągu 24 godzin od zakończenia rozwiązania.
żądanie
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
odpowiedź
{ "errorId": 0 }
POST/reportCorrectCaptchaOpcjonalnie: poinformuj nas, że rozwiązanie zostało ZAAKCEPTOWANE przez stronę docelową. Szczególnie przydatne dla typów zwracających współrzędne (np. suwak Shopee), gdzie zwracamy pozycję, a przeciągnięcie wykonuje Twoja przeglądarka. Ten raport to nasz jedyny sygnał rzeczywistej dokładności. Jeden raport na zadanie, w ciągu 24 godzin, nigdy nie wpływa na ceny.
żądanie
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
odpowiedź
{ "errorId": 0 }
POST/reportIncorrectCaptchaOpcjonalnie: poinformuj nas, że rozwiązanie zostało ODRZUCONE przez stronę docelową. Zasila to samo śledzenie rzeczywistej dokładności co /reportCorrectCaptcha. Jeden raport na zadanie, w ciągu 24 godzin, nigdy nie wpływa na ceny.
żądanie
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
odpowiedź
{ "errorId": 0 }

Obsługiwane typy zadań

Ładowanie…

Aktualna lista włączonych typów zadań, pogrupowana według dostawcy captcha. Ceny i średni czas rozwiązania aktualizują się automatycznie na podstawie telemetrii klastra.

Ładowanie typów zadań…

Limity żądań

Limity są egzekwowane dla konta, łącznie dla wszystkich Twoich kluczy API. Przekroczenie limitu zwraca kod błędu bez zużycia kredytów.

Domyślny
30 równoległych · 30 req/s

Każde nowe konto zaczyna od tego poziomu

Wyższa współbieżność
300+ równoległych · 100+ req/s

Otwórz zgłoszenie do pomocy technicznej z oczekiwanym wolumenem (bez osobnego poziomu cenowego, ta sama stawka za rozwiązanie)

zadania równoległe

Ile zadań możesz mieć jednocześnie w kolejce rozwiązywania. Zadanie wlicza się do limitu od createTask do zakończenia (sukces, niepowodzenie lub przekroczenie czasu).

limit żądań

Ile wywołań createTask możesz wykonać na sekundę. Okno przesuwne, egzekwowane dla konta. Przekroczenie limitu zwraca ERROR_RATE_LIMITED bez pobierania kredytów.

Kody błędów

Każdy błąd zwracany przez /createTask / /getTaskResult wraz z rozwiązaniem. Nieudane rozwiązania są automatycznie zwracane: kredyty natychmiast wracają na saldo.

Uwierzytelnianie

Problemy z kluczem API lub IP.
  • ERROR_KEY_DOES_NOT_EXIST

    Twój klucz API nie został rozpoznany.

    rozwiązanieSprawdź wartość w Panel → Klucze API. Klucze zaczynają się od `capzy_`. Zmienione klucze są natychmiast unieważniane.

    #
  • ERROR_IP_NOT_ALLOWED

    IP Twojego żądania nie znajduje się na liście dozwolonych adresów klucza API.

    rozwiązanieDodaj swoje IP do listy dozwolonych adresów klucza w Panel → Klucze API lub całkowicie usuń listę, jeśli nie potrzebujesz przypinania IP.

    #
  • ERROR_IP_BLOCKED

    Twoje IP jest tymczasowo zablokowane za wysyłanie zbyt wielu nieprawidłowych żądań.

    rozwiązanieBlokujemy adresy IP, które wysyłają ponad 100 nieprawidłowych żądań w ciągu 10 minut (z eskalacją). Napraw błąd powodujący nieprawidłowe żądania, a następnie poczekaj. Blokady wygasają automatycznie po czasie od 1 minuty do 24 godzin, zależnie od poziomu.

    #

Walidacja

Nieprawidłowe parametry zadania lub zły typ dla sitekey.
  • ERROR_INVALID_PARAMS

    Treść żądania była nieprawidłowa lub brakowało w niej wymaganych pól.

    rozwiązanieSprawdź, czy `clientKey` znajduje się na najwyższym poziomie, a `task` zawiera `type` oraz wymagany identyfikator (websiteURL/websiteKey/captchaId itp.). Wymagane parametry dla każdego typu znajdziesz w sekcji Typy zadań.

    #
  • ERROR_BAD_SITEKEY

    `websiteKey` nie jest zarejestrowany u żadnego dostawcy captcha, którego potrafimy zidentyfikować.

    rozwiązanieUpewnij się, że kopiujesz pełny sitekey ze strony docelowej (szukaj `data-sitekey`, `sitekey:` lub parametru w `grecaptcha.render` / `hcaptcha.render`).

    #
  • ERROR_TASK_NOT_SUPPORTED

    Przesłany `type` zadania nie jest typem captcha obecnie obsługiwanym przez Capzy.

    rozwiązaniePełną listę włączonych typów znajdziesz poniżej w sekcji Typy zadań. Jeśli potrzebujesz captchy spoza listy, otwórz zgłoszenie, a nadamy jej priorytet.

    #
  • ERROR_WRONG_TASK_TYPE

    Typ zadania nie pasuje do faktycznego dostawcy sitekey.

    rozwiązanieWstępnie sprawdzamy sitekey u jego prawdziwego dostawcy. Odpowiedź z błędem zawiera pole `recommended`: przełącz się na ten typ zadania. (Bez pobierania kredytów).

    #
  • ERROR_PROXY_REQUIRED

    Ta captcha jest powiązana z IP: jej tokeny są przypisane do IP, z którego zostały rozwiązane.

    rozwiązaniePrzełącz się na wariant `*Task` (zamiast `*TaskProxyLess`) i przekaż `proxyAddress` zgodny z IP, z którego wyślesz token. Dotyczy: Cloudflare Challenge, CaptchaFox, AWS WAF, DataDome, PerimeterX, Kasada, Akamai, Imperva.

    #
  • ERROR_NO_PROXY

    Pola proxy są wymagane dla tego typu zadania, ale ich brakowało.

    rozwiązanieDołącz `proxyType`, `proxyAddress`, `proxyPort` (i opcjonalnie `proxyLogin`/`proxyPassword`/`userAgent`) w treści zadania.

    #
  • ERROR_PROXY_CONNECT_REFUSED

    Podane proxy odrzuciło połączenie.

    rozwiązanieSprawdź dane logowania proxy, osiągalność hosta i to, czy IP działa. Najpierw wypróbuj to samo proxy z własnego komputera, aby wykluczyć problemy po stronie dostawcy.

    #

Limity żądań

Limity współbieżności / na sekundę / wskaźnika zwrotów.
  • ERROR_MAX_TASKS_REACHED

    Osiągnięto limit zadań równoległych dla poziomu Twojego konta.

    rozwiązaniePoczekaj na zakończenie trwających zadań, zanim prześlesz kolejne. Domyślny poziom Regular to 30 zadań równoległych. Skontaktuj się z pomocą techniczną, aby go podwyższyć.

    #
  • ERROR_RATE_LIMITED

    Wysyłasz /createTask szybciej, niż pozwala Twój limit żądań.

    rozwiązanieZwolnij i spróbuj ponownie. Domyślny poziom Regular to 30 req/s w oknie przesuwnym. Przekroczenie limitu nie zużywa kredytów.

    #
  • ERROR_NO_SLOT_AVAILABLE

    Przepustowość klastra jest tymczasowo wyczerpana.

    rozwiązanieSpróbuj ponownie za kilka sekund (to stan przejściowy). Jeśli utrzymuje się przez kilka minut, sprawdź status.capzy.ai.

    #
  • ERROR_SYSTEM_MAINTENANCE

    Capzy jest w trakcie zaplanowanych prac konserwacyjnych.

    rozwiązanieSpróbuj ponownie po zakończeniu okna konserwacji. Wcześniejsze powiadomienia publikujemy na stronie statusu.

    #

Wyniki rozwiązań

Co zwrócił solver. Nieudane rozwiązania są automatycznie zwracane.
  • ERROR_TIMEOUT

    Zadanie nie zakończyło się w limicie czasu dla danego typu.

    rozwiązanieAutomatycznie zwrócone, bez opłat. Większość przekroczeń czasu jest przejściowa. Jeśli konkretna captcha regularnie przekracza limit czasu, otwórz zgłoszenie z UUID zadania.

    #
  • ERROR_CAPTCHA_UNSOLVABLE

    Solver wyczerpał budżet ponowień dla tego wyzwania.

    rozwiązanieAutomatycznie zwrócone, bez opłat. Typowe przyczyny: nieaktualny sitekey, websiteURL nie pasuje do domeny osadzającej, captcha została wyłączona przez stronę docelową.

    #
  • ERROR_NULL_RESULT

    Solver zakończył działanie, ale nie zwrócił tokenu.

    rozwiązanieAutomatycznie zwrócone. Zwykle oznacza, że strona docelowa usunęła captchę w trakcie rozwiązywania. Spróbuj ponownie, a jeśli problem się utrzymuje, otwórz zgłoszenie.

    #
  • ERROR_INTERNAL

    Nieoczekiwany błąd w potoku rozwiązywania.

    rozwiązanieAutomatycznie zwrócone. Spróbuj ponownie (to rzadkie). Jeśli pojawiają się w ciasnej pętli, otwórz zgłoszenie z UUID zadania.

    #
  • ERROR_ZERO_BALANCE

    Saldo konta jest za niskie, aby pokryć koszt zadania.

    rozwiązanieDoładuj kredyty w Panel → Rozliczenia. Nieudane rozwiązania są automatycznie zwracane, więc płacisz tylko za udane tokeny.

    #

Raportowanie wyników

Błędy specyficzne dla /reportScore (informacja zwrotna o jakości V3).
  • ERROR_TASK_NOT_FOUND

    /reportScore: taskId nie należy do Twojego konta lub zostało usunięte.

    rozwiązanieRaporty wyniku muszą dotyczyć Twojego zadania i muszą zostać złożone w ciągu 24 h od zakończenia rozwiązania.

    #
  • ERROR_TASK_NOT_READY

    /reportScore: zadanie jest nadal przetwarzane lub już się nie powiodło.

    rozwiązanieOcenić można tylko zadania `ready`. Przed zgłoszeniem poczekaj, aż /getTaskResult zwróci ready.

    #
  • ERROR_REPORT_TOO_LATE

    /reportScore: od zakończenia rozwiązania minęło ponad 24 h.

    rozwiązanieZgłaszaj wyniki w ciągu kilku minut od wywołania siteverify. Wtedy dane są najbardziej przydatne dla naszego panelu jakości V3.

    #
06

Playground kodu

Kompletne działające przykłady w każdym popularnym języku. Skopiuj, wklej klucz API, uruchom.

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)
Podgląd wynikuSukces (200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

Zintegruj się w mniej niż 60 sekund.

$0.10 darmowych kredytów przy rejestracji. Bez karty kredytowej.

Odbierz darmowy klucz API →