createTask

Submit a CAPTCHA solving task to uCaptcha. The API selects the optimal provider based on your routing settings and returns a task ID for polling.

Endpoint

POST https://api.ucaptcha.net/createTask

Request

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "RecaptchaV2TaskProxyless",
    "websiteURL": "https://example.com",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  },
  "callbackUrl": "https://your-server.com/callback",
  "selectionMode": "autoFastest",
  "provider": "capsolver"
}

Request Parameters

Parameter	Type	Required	Description
clientKey	string	Yes	Your API key
task	object	Yes	Task configuration object
task.type	string	Yes	Task type identifier (see Task Types in the sidebar)
callbackUrl	string	No	URL to receive the result via webhook when the task completes
selectionMode	string	No	Override routing for this request (see below)
provider	string	No	Force a specific provider (e.g., capsolver, 2captcha)

The task object requires different fields depending on the task type. At minimum, most token-based tasks require type, websiteURL, and websiteKey. See the individual task type pages for full parameter details.

Selection Modes

The selectionMode parameter lets you override your API key’s default routing settings for a single request.

Value	Description
autoCheapest	Routes to the cheapest available provider. Equivalent to setting speedWeight to 10.
autoFastest	Routes to the fastest available provider. Equivalent to setting speedWeight to 90.
autoMostReliable	Balances cost and speed with emphasis on reliability. Equivalent to setting speedWeight to 50.
priority	Same behavior as autoMostReliable. This is the default if no mode is specified.

Note

The selectionMode parameter overrides the routing settings configured on your API key for this single request only. It does not change your key’s saved settings.

Response

Async Task (most task types)

Most tasks are solved asynchronously. The response includes a taskId that you use to poll for results.

{
  "errorId": 0,
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

Sync Task (recognition tasks)

Some task types such as ImageToTextTask may return the solution immediately without requiring polling.

{
  "errorId": 0,
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready",
  "solution": {
    "text": "abc123"
  }
}

Response Parameters

Field	Type	Description
errorId	number	0 for success, 1 for error
taskId	string	Unique task identifier (UUID)
status	string	processing for async tasks, ready for sync tasks that solved immediately
solution	object	Solution object (only present when status is ready)
errorCode	string	Error code (only present when errorId is 1)
errorDescription	string	Human-readable error message (only present when errorId is 1)

Tip

Billing: Your balance is pre-deducted when a task is created based on the estimated cost. If the task fails, the charge is automatically refunded. If the actual cost differs from the estimate upon completion, your balance is reconciled accordingly.

Code Examples

cURL

curl -X POST https://api.ucaptcha.net/createTask \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "RecaptchaV2TaskProxyless",
      "websiteURL": "https://example.com",
      "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
    }
  }'

Python

import requests

response = requests.post("https://api.ucaptcha.net/createTask", json={
    "clientKey": "YOUR_API_KEY",
    "task": {
        "type": "RecaptchaV2TaskProxyless",
        "websiteURL": "https://example.com",
        "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
    }
})

data = response.json()

if data["errorId"] == 0:
    task_id = data["taskId"]
    print(f"Task created: {task_id}")
else:
    print(f"Error: {data['errorCode']} - {data['errorDescription']}")

JavaScript

const response = await fetch("https://api.ucaptcha.net/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: "YOUR_API_KEY",
    task: {
      type: "RecaptchaV2TaskProxyless",
      websiteURL: "https://example.com",
      websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    },
  }),
});

const data = await response.json();

if (data.errorId === 0) {
  console.log(`Task created: ${data.taskId}`);
} else {
  console.error(`Error: ${data.errorCode} - ${data.errorDescription}`);
}