Skip to content
clearance.rest

Solve a captcha

POST
/resolve
curl --request POST \
  --url https://api.clearance.rest/captchas/resolve \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'X-Service-Timeout: 45000' \
  --data '{ "provider": "capsolver", "task": { "type": "ImageToTextTask", "body": "<base64 image>" } }'

Sends the task to the chosen provider and holds the connection open until a solution arrives or the timeout elapses.

task is passed to the provider as-is, so its shape depends on provider:

  • capsolver: a Capsolver task, for example { "type": "ImageToTextTask", "body": "<base64>" }.
  • 2captcha: a 2Captcha task object. - 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.

The response is not normalised: it is the provider’s own response with jobId and waitedMs added. A provider-side failure (for example 2Captcha’s code: "ERROR_…" or NoneCap’s status: "failed") is still HTTP 200; read the failure from the provider-specific fields.

If the project has no account for the requested provider, the request is rejected with 400.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
X-Service-Timeout
integer
>= 1

Maximum time to wait, in milliseconds. Must be a positive integer. When the wait exceeds it, the response is HTTP 200 with error: "timeout". It can only lower the service’s own ceiling, never raise it.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
provider

Which solver to use.

string
default: capsolver
Allowed values: capsolver 2captcha nonecap nonecap-browser
task
required

Provider-specific task, passed through unchanged.

object
key
additional properties
any
Examples

Capsolver, image to text

{
  "provider": "capsolver",
  "task": {
    "type": "ImageToTextTask",
    "body": "<base64 image>"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

The provider’s response plus jobId and waitedMs, or a timeout (error: "timeout").

Media typeapplication/json
Any of:

The provider’s response, unmodified, with jobId and waitedMs added. The extra fields depend on the provider (see the examples).

object
jobId
required

Identifier of this solve, for correlation in support requests.

string format: uuid
waitedMs
required

How long the request waited, in milliseconds.

integer
key
additional properties
any
Examples
{
  "jobId": "6f1c1a4e-2f0e-4c39-9d1b-3f7a7f8c2b10",
  "waitedMs": 1234,
  "errorId": 0,
  "taskId": "8b1c…",
  "status": "ready",
  "solution": {
    "text": "abc123"
  }
}

400

Section titled “400”

Invalid JSON body, unknown provider, missing task, invalid X-Service-Timeout, or the project has no account for the provider.

Media typeapplication/json

Error envelope returned with a non-2xx status.

object
success
required
boolean
error
required

Human-readable error message.

string
Examples
{
  "success": false,
  "error": "invalid json body"
}

401

Section titled “401”

The X-API-Key header is missing or invalid.

Media typeapplication/json

Error envelope returned with a non-2xx status.

object
success
required
boolean
error
required

Human-readable error message.

string
Example
{
  "success": false,
  "error": "geçersiz API anahtarı"
}

502

Section titled “502”

The provider call threw (network error, auth error, or the provider’s own error field).

Media typeapplication/json
object
jobId
required
string
error
required
string
Examplegenerated
{
  "jobId": "example",
  "error": "example"
}