Aller au contenu

Documentation API

Trois endpoints, des exemples de code complets dans six langages. Intégrez en moins de 60 secondes le cluster de solveurs hautes performances de Capzy.

Démarrage rapide

étape 1
POST /createTask

Envoyez le type de captcha + les paramètres du site. Vous recevez instantanément un taskId.

étape 2
POST /getTaskResult

Interrogez toutes les ~1 s jusqu’à ce que le statut soit ready. Le jeton arrive dans l’objet solution.

étape 3
POST /getBalance

Vérifiez les crédits restants. Les résolutions échouées y sont remboursées automatiquement.

url de basehttps://api.capzy.aiauthentification via clientKey dans le corps de la requête

Endpoints

POST/createTaskCréer une nouvelle tâche de résolution de captcha
requête
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
réponse
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultInterroger le résultat d’une tâche
requête
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
réponse
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceConsulter le solde du compte
requête
{ "clientKey": "capzy_..." }
réponse
{ "errorId": 0, "balance": 9.50 }
POST/reportScoreFacultatif : renvoyez le score vérifié par Google pour les tâches V3. Alimente la vue qualité V3 de votre tableau de bord. Un rapport par tâche ; les rapports doivent arriver dans les 24 heures suivant la fin de la résolution.
requête
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
réponse
{ "errorId": 0 }
POST/reportCorrectCaptchaFacultatif : indiquez-nous que la résolution a été ACCEPTÉE par le site cible. Particulièrement utile pour les types renvoyant des coordonnées (ex. slider Shopee), pour lesquels nous renvoyons une position et votre propre navigateur effectue le glissement. Ce rapport est notre seul signal de précision en conditions réelles. Un rapport par tâche, dans les 24 heures ; n’affecte jamais la tarification.
requête
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
réponse
{ "errorId": 0 }
POST/reportIncorrectCaptchaFacultatif : indiquez-nous que la résolution a été REFUSÉE par le site cible. Alimente le même suivi de précision en conditions réelles que /reportCorrectCaptcha. Un rapport par tâche, dans les 24 heures ; n’affecte jamais la tarification.
requête
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
réponse
{ "errorId": 0 }

Types de tâches pris en charge

Chargement…

Liste en direct des types de tâches actuellement activés, regroupés par fournisseur de captcha. Les prix et temps de résolution moyens se mettent à jour automatiquement à partir de la télémétrie du cluster.

Chargement des types de tâches…

Limites de débit

Les limites s’appliquent par compte, cumulées sur toutes les clés API que vous possédez. Dépasser la limite renvoie un code d’erreur sans consommer de crédits.

Par défaut
30 simultanées · 30 req/sec

Tous les nouveaux comptes démarrent ici

Concurrence supérieure
300+ simultanées · 100+ req/sec

Ouvrez un ticket de support en indiquant votre volume prévu (pas de palier tarifaire distinct, même tarif par résolution)

tâches simultanées

Le nombre de tâches que vous pouvez avoir en même temps dans la file de résolution. Une tâche compte dans votre limite depuis createTask jusqu’à sa fin (réussite, échec ou timeout).

limite de débit

Le nombre d’appels createTask que vous pouvez effectuer par seconde. Fenêtre glissante, appliquée par compte. Dépasser la limite renvoie ERROR_RATE_LIMITED sans débit de crédits.

Codes d’erreur

Toutes les erreurs renvoyées par /createTask / /getTaskResult, avec leur correctif. Les résolutions échouées sont remboursées automatiquement : les crédits reviennent immédiatement sur votre solde.

Authentification

Problèmes liés à votre clé API ou à votre IP.
  • ERROR_KEY_DOES_NOT_EXIST

    Votre clé API n’a pas été reconnue.

    correctifVérifiez la valeur dans Tableau de bord → Clés API. Les clés commencent par `capzy_`. Les clés renouvelées sont invalidées immédiatement.

    #
  • ERROR_IP_NOT_ALLOWED

    L’IP de votre requête ne figure pas dans la liste d’autorisation de la clé API.

    correctifAjoutez votre IP à la liste d’autorisation de la clé dans Tableau de bord → Clés API, ou supprimez entièrement la liste si vous n’avez pas besoin de restreindre par IP.

    #
  • ERROR_IP_BLOCKED

    Votre IP est temporairement bannie pour avoir envoyé trop de requêtes invalides.

    correctifNous bannissons les IP qui envoient plus de 100 requêtes invalides en 10 minutes (de façon progressive). Corrigez le bug à l’origine des requêtes invalides, puis patientez. Les bannissements expirent automatiquement au bout de 1 minute à 24 heures selon le niveau.

    #

Validation

Paramètres de tâche incorrects ou mauvais type pour la sitekey.
  • ERROR_INVALID_PARAMS

    Le corps de la requête est mal formé ou des champs obligatoires sont manquants.

    correctifVérifiez que `clientKey` est au premier niveau et que `task` contient `type` ainsi que l’identifiant requis (websiteURL/websiteKey/captchaId/etc). Consultez la section Types de tâches pour les paramètres requis par type.

    #
  • ERROR_BAD_SITEKEY

    La `websiteKey` n’est enregistrée auprès d’aucun fournisseur de captcha que nous puissions identifier.

    correctifAssurez-vous de copier la sitekey complète depuis la page cible (cherchez `data-sitekey`, `sitekey:` ou le paramètre dans `grecaptcha.render` / `hcaptcha.render`).

    #
  • ERROR_TASK_NOT_SUPPORTED

    Le `type` de tâche soumis n’est pas un type de captcha actuellement pris en charge par Capzy.

    correctifConsultez la section Types de tâches ci-dessous pour la liste complète des types activés. Si vous avez besoin d’un captcha non listé, ouvrez un ticket et nous le traiterons en priorité.

    #
  • ERROR_WRONG_TASK_TYPE

    Le type de tâche ne correspond pas au fournisseur réel de la sitekey.

    correctifNous vérifions en amont les sitekeys auprès de leur fournisseur réel. La réponse d’erreur inclut un champ `recommended` : passez à ce type de tâche. (Aucun crédit débité.)

    #
  • ERROR_PROXY_REQUIRED

    Ce captcha est lié à l’IP : ses jetons sont liés à l’IP qui les a résolus.

    correctifPassez à la variante `*Task` (au lieu de `*TaskProxyLess`) et indiquez un `proxyAddress` correspondant à l’IP que vous utiliserez pour soumettre le jeton. Concerne : Cloudflare Challenge, CaptchaFox, AWS WAF, DataDome, PerimeterX, Kasada, Akamai, Imperva.

    #
  • ERROR_NO_PROXY

    Les champs proxy sont obligatoires pour ce type de tâche, mais ils sont absents.

    correctifIncluez `proxyType`, `proxyAddress`, `proxyPort` (et éventuellement `proxyLogin`/`proxyPassword`/`userAgent`) dans le corps de votre tâche.

    #
  • ERROR_PROXY_CONNECT_REFUSED

    Le proxy fourni a refusé la connexion.

    correctifVérifiez les identifiants du proxy, l’accessibilité de l’hôte et que l’IP est active. Testez d’abord le même proxy depuis votre propre machine pour isoler les problèmes du fournisseur.

    #

Limites de débit

Limites de concurrence / par seconde / de taux de remboursement.
  • ERROR_MAX_TASKS_REACHED

    Vous avez atteint la limite de tâches simultanées de votre niveau de compte.

    correctifAttendez la fin des tâches en cours avant d’en soumettre d’autres. Le niveau Standard par défaut autorise 30 tâches simultanées ; contactez le support pour passer à un niveau supérieur.

    #
  • ERROR_RATE_LIMITED

    Vous soumettez des /createTask plus vite que votre limite de débit.

    correctifRalentissez et réessayez. Le niveau Standard par défaut est de 30 req/sec en fenêtre glissante. Dépasser la limite ne consomme pas de crédits.

    #
  • ERROR_NO_SLOT_AVAILABLE

    La capacité du cluster est temporairement saturée.

    correctifRéessayez au bout de quelques secondes (c’est passager). Si cela persiste pendant plusieurs minutes, consultez status.capzy.ai.

    #
  • ERROR_SYSTEM_MAINTENANCE

    Capzy est en maintenance programmée.

    correctifRéessayez après la fenêtre de maintenance. Nous publions des avis à l’avance sur la page de statut.

    #

Résultats de résolution

Ce que le solveur a renvoyé. Les résolutions échouées sont remboursées automatiquement.
  • ERROR_TIMEOUT

    La tâche ne s’est pas terminée dans le délai maximal prévu pour son type.

    correctifRemboursé automatiquement, sans frais. La plupart des timeouts sont passagers. Si un captcha précis expire systématiquement, ouvrez un ticket avec l’UUID de la tâche.

    #
  • ERROR_CAPTCHA_UNSOLVABLE

    Le solveur a épuisé son budget de tentatives sur ce défi.

    correctifRemboursé automatiquement, sans frais. Causes fréquentes : sitekey périmée, websiteURL ne correspondant pas au domaine d’intégration, captcha désactivé par le site cible.

    #
  • ERROR_NULL_RESULT

    Le solveur a terminé mais n’a renvoyé aucun jeton.

    correctifRemboursé automatiquement. Indique généralement que le site cible a retiré le captcha en cours de résolution. Réessayez ; si cela persiste, ouvrez un ticket.

    #
  • ERROR_INTERNAL

    Erreur inattendue dans le pipeline de résolution.

    correctifRemboursé automatiquement. Réessayez (ces erreurs sont rares). Si vous les voyez en boucle, ouvrez un ticket avec l’UUID de la tâche.

    #
  • ERROR_ZERO_BALANCE

    Solde du compte insuffisant pour couvrir le coût de la tâche.

    correctifAjoutez des crédits depuis Tableau de bord → Facturation. Les résolutions échouées sont remboursées automatiquement : vous ne payez que les jetons réussis.

    #

Rapports de score

Erreurs propres à /reportScore (retour qualité V3).
  • ERROR_TASK_NOT_FOUND

    /reportScore : le taskId n’appartient pas à votre compte ou a été purgé.

    correctifLes rapports de score doivent concerner une tâche qui vous appartenait et être envoyés dans les 24 h suivant la fin de la résolution.

    #
  • ERROR_TASK_NOT_READY

    /reportScore : la tâche est toujours en cours ou a déjà échoué.

    correctifSeules les tâches `ready` peuvent recevoir un score. Attendez que /getTaskResult renvoie ready avant de faire votre rapport.

    #
  • ERROR_REPORT_TOO_LATE

    /reportScore : plus de 24 h se sont écoulées depuis la fin de la résolution.

    correctifEnvoyez les scores dans les minutes qui suivent votre appel siteverify. C’est à ce moment que les données sont les plus utiles pour notre tableau de bord de qualité V3.

    #
06

Playground de code

Des exemples complets et fonctionnels dans tous les principaux langages. Copiez, collez votre clé API, exécutez.

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)
Aperçu de la sortieSuccès (200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

Intégrez en moins de 60 secondes.

$0.10 de crédits offerts à l’inscription. Aucune carte bancaire requise.

Obtenez votre clé API gratuite →