Skip to content
YesCaptchaYesCaptcha Docs

Requests and responses

MarkdownOpen in ChatGPTOpen in Claude

Every method takes an HTTPS POST with a JSON body (only /useragent is GET), is authenticated with the clientKey in the body, and returns JSON: errorId 0 means success, 1 means failure with an errorCode. Solving a captcha takes two steps: createTask creates a task and getTaskResult is polled every 5 seconds for the result. Synchronous types return the result from createTask directly.

Request

Section titled “Request”
终端窗口
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) or https://cn.yescaptcha.com (China). See Endpoints.
  • The body is JSON, sent with Content-Type: application/json, under 6 MB. JSON cannot contain comments.
  • Every request includes clientKey, copied in full from the dashboard.
  • With Python requests use json=data, not data=data (the latter sends a form and returns ERROR_TASK_ABSENT or ERROR_REQUIRED_FIELDS).

Response

Section titled “Response”

Success:

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

Failure:

{ "errorId": 1, "errorCode": "ERROR_ZERO_BALANCE", "errorDescription": "帐户余额不足" }
Field Description
errorId 0 success, 1 failure
errorCode The error code on failure; meanings and fixes in Error codes
errorDescription A text description of the failure (Chinese for most codes)
taskId The task ID
status processing or ready
solution The result; its fields depend on the task type (see each task type page)

Check errorId and errorCode in your code, not the wording of errorDescription, which may change.

Synchronous and asynchronous

Section titled “Synchronous and asynchronous”
Asynchronous Synchronous
Which types Token types (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), the Cloudflare challenge page, ImageToTextTask, ImageToTextTaskM1 Image recognition (names ending in Classification), ImageToTextTaskOcrBase, ImageToTextTaskMuggle
createTask returns taskId status: "ready" and solution
Getting the result Call getTaskResult every 5 seconds Nothing more to do

The “Mode” column in Task types and pricing shows which applies to each type.

Polling

Section titled “Polling”
  1. After createTask returns a taskId, wait 5 seconds and call getTaskResult.
  2. On status: "processing", wait another 5 seconds and try again; on status: "ready", the result is in solution.
  3. On errorId: 1, stop polling this task and handle the errorCode.
  • Repeated queries for the same taskId within 5 seconds return processing right away; polling faster does not get the result sooner.
  • A task runs for at most about 110 seconds (180 to 220 seconds for a few types); after that it returns ERROR_TASK_TIMEOUT and the points are refunded.
  • Results are kept for about 10 minutes; after that the taskId expires and queries return ERROR_TASKID_INVALID.
  • Queries are free; only creating a task is charged.

Message language

Section titled “Message language”

For automatic pauses, cached invalid parameters and stop-polling hints, errorDescription follows the Accept-Language request header: Chinese if it starts with zh, English for any other language, and both if the header is absent. Other error descriptions are unaffected.

Next

Section titled “Next”