Solicitudes y respuestas

Todos los métodos usan HTTPS POST con un cuerpo JSON (solo /useragent es GET), se autentican con el clientKey del cuerpo y devuelven JSON: errorId 0 significa éxito y 1 significa fallo, con un errorCode. Resolver un captcha tiene dos pasos: createTask crea la tarea y getTaskResult se consulta cada 5 segundos para obtener el resultado. Los tipos síncronos devuelven el resultado directamente en createTask.

Solicitud

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 (global) o https://cn.yescaptcha.com (China). Consulta Direcciones de acceso.
• El cuerpo es JSON, se envía con el encabezado Content-Type: application/json y no puede superar 6 MB. El JSON no admite comentarios.
• Cada solicitud debe incluir clientKey, copiado completo desde el Panel.

Precaución

Con requests de Python usa json=data, no data=data. Esta última envía un formulario y devuelve ERROR_TASK_ABSENT o ERROR_REQUIRED_FIELDS.

Respuesta

Éxito:

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

Fallo:

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

Campo	Descripción
errorId	0 éxito, 1 fallo
errorCode	Código de error en caso de fallo; su significado y cómo resolverlo están en Códigos de error
errorDescription	Descripción en texto del motivo del fallo
taskId	ID de tarea
status	processing (en proceso) o ready (completada)
solution	Resultado del reconocimiento; sus campos dependen del tipo de tarea (consulta la página de cada tipo)

Para evaluar el resultado, usa errorId y errorCode; no analices el texto de errorDescription, ya que puede cambiar.

Síncrono y asíncrono

	Asíncrono	Síncrono
Qué tipos	Tipos que devuelven token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), página de verificación de Cloudflare, ImageToTextTask, ImageToTextTaskM1	Reconocimiento de imágenes (nombres que terminan en Classification), ImageToTextTaskOcrBase, ImageToTextTaskMuggle
createTask devuelve	taskId	status: "ready" y solution
Cómo obtener el resultado	Llama a getTaskResult cada 5 segundos	No hace falta consultar de nuevo

Para saber a qué grupo pertenece cada tipo, consulta la columna “Modo de respuesta” de Tipos de tarea y precios.

Consulta periódica (polling)

1. Cuando createTask devuelva un taskId, espera 5 segundos y llama a getTaskResult.
2. Si devuelve status: "processing", espera otros 5 segundos y reintenta; si devuelve status: "ready", el resultado está en solution.
3. Si devuelve errorId: 1, deja de consultar esa tarea y gestiona el errorCode.

• Las consultas repetidas del mismo taskId dentro de 5 segundos devuelven processing de inmediato; consultar con más frecuencia no da el resultado antes.
• Una tarea se procesa como máximo unos 110 segundos (180 a 220 segundos en algunos tipos); si se supera, devuelve ERROR_TASK_TIMEOUT y se hace el reembolso de puntos automáticamente.
• El resultado se guarda en el servidor unos 10 minutos; después el taskId caduca y la consulta devuelve ERROR_TASKID_INVALID.
• Consultar el resultado no cobra puntos; solo se cobran al crear la tarea.

Idioma de los mensajes

En los avisos de pausa automática, caché de parámetros inválidos y fin de la consulta periódica, errorDescription se elige según el encabezado Accept-Language: si empieza por zh se devuelve en chino, con cualquier otro idioma se devuelve en inglés, y si no se envía el encabezado se devuelven ambos. Las descripciones de los demás códigos de error no cambian.

Siguiente paso

• createTask: crear una tarea
• getTaskResult: obtener el resultado
• Límite de tareas simultáneas y pausa automática: si hay demasiados errores, se pausa tu cuenta unos minutos