Requêtes et réponses

Toutes les méthodes reçoivent un POST HTTPS avec un corps JSON (seul /useragent est en GET), s’authentifient avec le clientKey du corps de la requête et renvoient du JSON : errorId à 0 signifie un succès, à 1 un échec accompagné d’un errorCode. Résoudre un captcha se fait en deux étapes : createTask crée la tâche, puis getTaskResult est interrogé toutes les 5 secondes pour obtenir le résultat. Les types synchrones renvoient directement le résultat dans createTask.

Requête

curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'

• Endpoint : https://api.yescaptcha.com (mondial) ou https://cn.yescaptcha.com (Chine). Voir Adresses d’accès.
• Le corps est au format JSON, envoyé avec l’en-tête Content-Type: application/json, et ne dépasse pas 6 MB. Le JSON ne peut pas contenir de commentaires.
• Chaque requête doit inclure clientKey, copié en entier depuis le tableau de bord.

Attention

Avec requests en Python, utilisez json=data et non data=data. Ce dernier envoie un formulaire et renvoie ERROR_TASK_ABSENT ou ERROR_REQUIRED_FIELDS.

Réponse

Succès :

{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

Échec :

{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}

Champ	Description
errorId	0 : succès, 1 : échec
errorCode	Code d’erreur en cas d’échec ; signification et solutions dans Codes d’erreur
errorDescription	Description textuelle de la cause de l’échec
taskId	ID de tâche
status	processing (en cours) ou ready (terminé)
solution	Résultat de la résolution ; les champs dépendent du type de tâche (voir la page de chaque type de tâche)

Dans votre code, appuyez-vous sur errorId et errorCode, pas sur le texte de errorDescription, qui peut changer.

Synchrone et asynchrone

	Asynchrone	Synchrone
Types concernés	Types qui renvoient un token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), page de vérification Cloudflare, ImageToTextTask, ImageToTextTaskM1	Reconnaissance d’images (noms se terminant par Classification), ImageToTextTaskOcrBase, ImageToTextTaskMuggle
createTask renvoie	taskId	status: "ready" et solution
Obtenir le résultat	Appelez getTaskResult toutes les 5 secondes	Rien de plus à faire

La colonne « Mode de retour » de Types de tâches et prix indique le mode de chaque type.

Interrogation périodique (polling)

1. Une fois le taskId renvoyé par createTask, attendez 5 secondes avant d’appeler getTaskResult.
2. Si la réponse est status: "processing", attendez encore 5 secondes puis réessayez ; si elle est status: "ready", le résultat se trouve dans solution.
3. Si la réponse est errorId: 1, arrêtez d’interroger cette tâche et traitez l’errorCode.

• Les requêtes répétées pour le même taskId dans un délai de 5 secondes renvoient immédiatement processing ; interroger plus souvent ne donne pas le résultat plus vite.
• Une tâche est traitée au maximum pendant environ 110 secondes (180 à 220 secondes pour quelques types) ; passé ce délai, elle renvoie ERROR_TASK_TIMEOUT et les points sont remboursés automatiquement.
• Les résultats sont conservés côté serveur environ 10 minutes ; ensuite le taskId expire et la requête renvoie ERROR_TASKID_INVALID.
• La consultation du résultat n’entraîne aucun débit de points ; seule la création de la tâche est débitée.

Langue des messages

Pour les messages de suspension automatique, de paramètres invalides mis en cache et d’arrêt de l’interrogation, errorDescription suit l’en-tête de requête Accept-Language : chinois si la valeur commence par zh, anglais pour toute autre langue, et les deux langues si l’en-tête est absent. Les descriptions des autres codes d’erreur ne sont pas concernées.

Étape suivante

• createTask : créer une tâche
• getTaskResult : obtenir le résultat
• Limite de tâches simultanées et suspension automatique : trop d’erreurs entraînent une suspension de quelques minutes