Solving captchas

POST /captchas/resolve sends a captcha task to a solver and keeps the request open until the solution is ready. One request, one result.

curl

curl -X POST https://api.clearance.rest/captchas/resolve \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "X-Service-Timeout: 60000" \
  -H "content-type: application/json" \
  -d '{
    "provider": "capsolver",
    "task": { "type": "ImageToTextTask", "body": "<base64 image>" }
  }'

Node.js

const solution = await clearanceRest.captchas.resolve({
  provider: 'capsolver',
  task: { type: 'ImageToTextTask', body: '<base64 image>' },
  timeout: 60000,
});
console.log(solution.value); // "abc123"

PHP

use ClearanceRest\Services\Captchas;

$solution = $client->captchas->resolve(
    task: ['type' => 'ImageToTextTask', 'body' => '<base64 image>'],
    provider: 'capsolver',
    timeout: 60_000,
);
echo Captchas::solutionValue($solution); // "abc123"

Providers

provider picks the solver and defaults to capsolver.

provider	task
capsolver	A Capsolver task, for example { "type": "ImageToTextTask", "body": "…" }.
2captcha	A 2Captcha task.
nonecap	NoneCap’s own request body, for example { "type": "hcaptcha", "sitekey": "…", "url": "https://…" }.
nonecap-browser	{ "url", "sitekey", "proxy"? }. sitekey is required. type and rqdata are not supported.

task is passed to the solver unchanged, so its shape is the solver’s own. Use the solver’s documentation for which task types and fields exist.

Your project must have an account for the provider you ask for. If it does not, the request returns 400.

Response

The response is not normalised. It is the solver’s own response with two fields added: jobId (an id you can quote to support) and waitedMs. The rest depends on the solver:

{ "jobId": "6f1c…", "waitedMs": 1234, "errorId": 0, "taskId": "8b1c…", "status": "ready", "solution": { "text": "abc123" } }

{ "jobId": "6f1c…", "waitedMs": 1234, "id": "12345", "code": "abc123" }

{ "jobId": "6f1c…", "waitedMs": 4021, "id": "solve_01HQF7K3JKWZX", "object": "solve", "status": "solved", "token": "P1_eyJ…" }

The first is Capsolver, the second 2Captcha, the third NoneCap. The SDKs read the token or text out of any of them for you (solution.value in Node, Captchas::solutionValue() in PHP).

Failures

• The solver could not solve it. This is still HTTP 200. Read the failure from the solver’s own fields (for example 2Captcha’s code: "ERROR_…" or NoneCap’s status: "failed"). The SDKs raise a typed error instead.

• The solver call itself failed (network, auth, the solver’s error field): HTTP 502 with { "jobId": "…", "error": "…" }.

• You ran out of time. HTTP 200 with error: "timeout":

  { "jobId": "6f1c…", "waitedMs": 60000, "error": "timeout" }

• Bad request (400): invalid JSON, an unknown provider, a missing task, or an invalid X-Service-Timeout.

Timeout

The wait lasts at most 10 minutes; lower it with X-Service-Timeout. See Timeouts. If your client disconnects, a solve at nonecap or nonecap-browser is cancelled at the solver.