uCaptcha

https://ucaptcha.net/docs/
Admin
uCaptcha is a universal CAPTCHA solver aggregator that routes solving tasks to optimal providers...
Tokens:162,797
Snippets:1,096
Trust Score:3.6
Update:5 days ago
Show doc for...
Tokens:
Raw
### Report Good Solution - GET Request

Source: https://ucaptcha.net/docs/api/legacy/res-php

Example GET request to report a good solution using action=reportgood.

```text
GET https://api.ucaptcha.net/res.php?key=YOUR_API_KEY&action=reportgood&id=TASK_ID
```

--------------------------------

### Success Example: Callback GET request

Source: https://ucaptcha.net/docs/api/callbacks

Example of a successful callback request with status=1 and a solution code.

```http
GET https://your-server.com/captcha-callback?captcha_id=550e8400-e29b-41d4-a716-446655440000&status=1&code=03AGdBq24PBCbwiDRkh3FOcMZ1Xi5sEKH...
```

--------------------------------

### Solution object example

Source: https://ucaptcha.net/docs/tasks/token/altcha

Example JSON solution object returned when the task is ready. Contains the proof-of-work token to submit with the form.

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

--------------------------------

### Report Bad Solution - GET Request

Source: https://ucaptcha.net/docs/api/legacy/res-php

Example GET request to report a bad solution using action=reportbad.

```text
GET https://api.ucaptcha.net/res.php?key=YOUR_API_KEY&action=reportbad&id=TASK_ID
```

--------------------------------

### cURL Example

Source: https://ucaptcha.net/docs/api/ucaptcha/get-balance

Example cURL command to call the getBalance endpoint. Replace YOUR_API_KEY with your actual key.

```bash
curl -X POST https://api.ucaptcha.net/getBalance \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "YOUR_API_KEY"
  }'
```

--------------------------------

### Get Balance - GET Request

Source: https://ucaptcha.net/docs/api/legacy/res-php

Example GET request to retrieve the account balance using action=getbalance.

```text
GET https://api.ucaptcha.net/res.php?key=YOUR_API_KEY&action=getbalance
```

--------------------------------

### JavaScript Example - Create and Poll Task

Source: https://ucaptcha.net/docs/tasks/token/hcaptcha

JavaScript async/await example using fetch to create a task and poll for the result. Logs token, respKey, and userAgent when ready.

```javascript
const API_KEY = "YOUR_API_KEY";


const { taskId } = await fetch("https://api.ucaptcha.net/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: API_KEY,
    task: {
      type: "HardCaptchaTokenProxyLess",
      websiteURL: "https://example.com/signup",
      websiteKey: "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
    }
  })
}).then(r => r.json());


while (true) {
  const result = await fetch("https://api.ucaptcha.net/getTaskResult", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: API_KEY, taskId })
  }).then(r => r.json());


  if (result.status === "ready") {
    console.log("Token:", result.solution.token);
    console.log("RespKey:", result.solution.respKey);
    console.log("UserAgent:", result.solution.userAgent);
    break;
  } else if (result.status === "failed") {
    console.error("Error:", result.errorDescription);
    break;
  }


  await new Promise(r => setTimeout(r, 5000));
}
```

--------------------------------

### Solution Object Example

Source: https://ucaptcha.net/docs/tasks/token/perimeterx

Example solution object containing the PerimeterX bypass token.

```json
{
  "token": "_pxhd=abc123xyz..."
}
```

--------------------------------

### JavaScript Example for ForterToken

Source: https://ucaptcha.net/docs/tasks/token/forter

JavaScript (async) example to create a ForterToken task and poll for the result, logging the token or error.

```javascript
const API_KEY = "YOUR_API_KEY";


const { taskId } = await fetch("https://api.ucaptcha.net/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: API_KEY,
    task: {
      type: "ForterToken",
      websiteURL: "https://example.com/checkout",
      proxy: "http://user:pass@1.2.3.4:8080"
    }
  })
}).then(r => r.json());


while (true) {
  const result = await fetch("https://api.ucaptcha.net/getTaskResult", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: API_KEY, taskId })
  }).then(r => r.json());


  if (result.status === "ready") {
    console.log("Token:", result.solution.token);
    break;
  } else if (result.status === "failed") {
    console.error("Error:", result.errorDescription);
    break;
  }
  await new Promise(r => setTimeout(r, 5000));
}
```

--------------------------------

### Example pricing response

Source: https://ucaptcha.net/docs/features/x402-payments

Example JSON response from the pricing endpoint, showing the Base network, payTo address, USDC asset, and flat prices for each task type.

```json
{
  "network": "base",
  "payTo": "0xADBA492fb2e41912d82161C7E5bFE4195E4c6637",
  "asset": "USDC",
  "pricesUsd": {
    "ReCaptchaV2TokenProxyLess": 0.0045,
    "HardCaptchaTokenProxyLess": 0.012,
    "TurnstileTokenProxyLess": 0.003,
    "ImageToTextTask": 0.001
  }
}
```

--------------------------------

### cURL Example

Source: https://ucaptcha.net/docs/api/deathbycaptcha/report

Example using cURL to report a CAPTCHA. Replace YOUR_API_KEY with your API key.

```bash
curl -X POST https://api.ucaptcha.net/api/captcha/550e8400-e29b-41d4-a716-446655440000/report \
  -d "authtoken=YOUR_API_KEY"
```

--------------------------------

### JavaScript Example: Create Task and Poll for Result

Source: https://ucaptcha.net/docs/tasks/token/lemin

JavaScript async/await example using fetch to create a LeminTokenProxyLess task and poll getTaskResult until ready or failed. Logs the token or error.

```javascript
const API_KEY = "YOUR_API_KEY";


const { taskId } = await fetch("https://api.ucaptcha.net/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: API_KEY,
    task: {
      type: "LeminTokenProxyLess",
      websiteURL: "https://example.com/contact",
      websiteKey: "CROPPED_d3d4d56_73ca4008925b4f83a3cb57"
    }
  })
}).then(r => r.json());


while (true) {
  const result = await fetch("https://api.ucaptcha.net/getTaskResult", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: API_KEY, taskId })
  }).then(r => r.json());


  if (result.status === "ready") {
    console.log("Token:", result.solution.token);
    break;
  } else if (result.status === "failed") {
    console.error("Error:", result.errorDescription);
    break;
  }


  await new Promise(r => setTimeout(r, 5000));
}
```

--------------------------------

### JavaScript Example: Create Task and Poll for Result

Source: https://ucaptcha.net/docs/tasks/token/temu

JavaScript (async) example that creates a TemuTokenProxyLess task and polls for the result using fetch. Logs the token when ready or the error description on failure, waiting 5 seconds between polls.

```javascript
const API_KEY = "YOUR_API_KEY";


const { taskId } = await fetch("https://api.ucaptcha.net/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: API_KEY,
    task: {
      type: "TemuTokenProxyLess",
      websiteURL: "https://www.temu.com/login",
      websiteKey: "temu_site_key_abc123"
    }
  })
}).then(r => r.json());


while (true) {
  const result = await fetch("https://api.ucaptcha.net/getTaskResult", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: API_KEY, taskId })
  }).then(r => r.json());


  if (result.status === "ready") {
    console.log("Token:", result.solution.token);
    break;
  } else if (result.status === "failed") {
    console.error("Error:", result.errorDescription);
    break;
  }


  await new Promise(r => setTimeout(r, 5000));
}
```

--------------------------------

### Python Example

Source: https://ucaptcha.net/docs/api/deathbycaptcha/report

Example using Python requests library to report a CAPTCHA. Replace TASK_ID and YOUR_API_KEY.

```python
import requests


requests.post(
    "https://api.ucaptcha.net/api/captcha/TASK_ID/report",
    data={"authtoken": "YOUR_API_KEY"}
)
```

--------------------------------

### JavaScript Example: Create Task and Poll for Result

Source: https://ucaptcha.net/docs/tasks/token/capy

JavaScript async/await example using fetch to create a CapyTokenProxyLess task and poll getTaskResult until ready or failed. Logs the token or error.

```javascript
const API_KEY = "YOUR_API_KEY";


const { taskId } = await fetch("https://api.ucaptcha.net/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: API_KEY,
    task: {
      type: "CapyTokenProxyLess",
      websiteURL: "https://example.com/form",
      websiteKey: "PUZZLE_Abc1dEFghIJKLMnop2"
    }
  })
}).then(r => r.json());


while (true) {
  const result = await fetch("https://api.ucaptcha.net/getTaskResult", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: API_KEY, taskId })
  }).then(r => r.json());


  if (result.status === "ready") {
    console.log("Token:", result.solution.token);
    break;
  } else if (result.status === "failed") {
    console.error("Error:", result.errorDescription);
    break;
  }


  await new Promise(r => setTimeout(r, 5000));
}
```

--------------------------------

### JavaScript Example for VercelToken

Source: https://ucaptcha.net/docs/tasks/token/vercel

JavaScript async/await example using fetch to create a VercelToken task and poll for the result. Logs the token or error. Polls every 5 seconds.

```javascript
const API_KEY = "YOUR_API_KEY";


const { taskId } = await fetch("https://api.ucaptcha.net/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: API_KEY,
    task: {
      type: "VercelToken",
      websiteURL: "https://example.vercel.app/api/data"
    }
  })
}).then(r => r.json());


while (true) {
  const result = await fetch("https://api.ucaptcha.net/getTaskResult", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: API_KEY, taskId })
  }).then(r => r.json());


  if (result.status === "ready") {
    console.log("Token:", result.solution.token);
    break;
  } else if (result.status === "failed") {
    console.error("Error:", result.errorDescription);
    break;
  }
  await new Promise(r => setTimeout(r, 5000));
}
```

--------------------------------

### Request example for Kasada task

Source: https://ucaptcha.net/docs/api/riskbypass/submit

Example JSON request body for a Kasada task. Includes token, task_type, target_url, and proxy.

```json
{
  "token": "YOUR_API_KEY",
  "task_type": "kasada",
  "target_url": "https://example.com/api/checkout",
  "proxy": "http://user:pass@1.2.3.4:8080"
}
```

--------------------------------

### cURL example

Source: https://ucaptcha.net/docs/api/riskbypass/get-result

Example cURL command to poll for a task result. Replace YOUR_API_KEY with your actual API key.

```bash
curl https://api.ucaptcha.net/task/result/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Solution Object

Source: https://ucaptcha.net/docs/tasks/token/atbcaptcha

Example solution object returned when the task is ready, containing the atbCAPTCHA verification token.

```json
{
  "token": "v1.e30.eyJhdXRoIjoiMTIzNDU2Nzg5...MCJ9"
}
```

--------------------------------

### Python Example

Source: https://ucaptcha.net/docs/api/ucaptcha/get-balance

Python script using requests to call getBalance and print the balance or error.

```python
import requests


response = requests.post("https://api.ucaptcha.net/getBalance", json={
    "clientKey": "YOUR_API_KEY"
})


data = response.json()


if data["errorId"] == 0:
    print(f"Balance: ${data['balance']:.4f}")
else:
    print(f"Error: {data['errorCode']} - {data['errorDescription']}")
```

--------------------------------

### JavaScript Example

Source: https://ucaptcha.net/docs/api/ucaptcha/get-balance

JavaScript code using fetch to call getBalance and log the balance or error.

```javascript
const response = await fetch("https://api.ucaptcha.net/getBalance", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: "YOUR_API_KEY",
  }),
});


const data = await response.json();


if (data.errorId === 0) {
  console.log(`Balance: $${data.balance.toFixed(4)}`);
} else {
  console.error(`Error: ${data.errorCode} - ${data.errorDescription}`);
}
```

--------------------------------

### Success Response (Ready)

Source: https://ucaptcha.net/docs/api/overview

Example success response when a task is complete and solution is available.

```json
{
  "errorId": 0,
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "03AGdBq24PBCbwiDR..."
  }
}
```

--------------------------------

### Success response

Source: https://ucaptcha.net/docs/api/riskbypass/submit

Example success response with ok true and a task_id.

```json
{
  "ok": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

--------------------------------

### Solution Object JSON with Forter Token

Source: https://ucaptcha.net/docs/tasks/token/forter

Example solution object containing the Forter session token.

```json
{
  "token": "eyJhbGciOiJSUzI1NiJ9.eyJ..."
}
```

--------------------------------

### Python example for /api/user

Source: https://ucaptcha.net/docs/api/deathbycaptcha/account

Python script using requests to fetch the account balance. Requires the requests library. Replace YOUR_API_KEY with your actual API key.

```python
import requests


resp = requests.post("https://api.ucaptcha.net/api/user", data={
    "authtoken": "YOUR_API_KEY"
})
balance = resp.json()["balance"]
print(f"Balance: ${balance:.2f}")
```

--------------------------------

### Failure Example: Callback GET request

Source: https://ucaptcha.net/docs/api/callbacks

Example of a failed callback request with status=0 and no code parameter.

```http
GET https://your-server.com/captcha-callback?captcha_id=550e8400-e29b-41d4-a716-446655440000&status=0
```

--------------------------------

### Python Example with requests

Source: https://ucaptcha.net/docs/api/riskbypass/balance

Python script using the requests library to fetch the balance and print it in USD and credits. Requires the requests library.

```python
import requests


resp = requests.post("https://api.ucaptcha.net/api/user/balance", json={
    "token": "YOUR_API_KEY"
})
credits = resp.json()["balance"]
print(f"Balance: ${credits / 1000:.2f} ({credits} credits)")
```

--------------------------------

### Poll Task Result - GET Request

Source: https://ucaptcha.net/docs/api/legacy/res-php

Example GET request to poll a task result using the action=get operation.

```text
GET https://api.ucaptcha.net/res.php?key=YOUR_API_KEY&action=get&id=TASK_ID
```

--------------------------------

### JavaScript Example: Create Task and Poll for Solution

Source: https://ucaptcha.net/docs/tasks/token/prosopo

JavaScript (async) using fetch to create a ProsopoTokenProxyLess task, poll getTaskResult until ready, and log the token.

```javascript
const API_KEY = "YOUR_API_KEY";


const { taskId } = await fetch("https://api.ucaptcha.net/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: API_KEY,
    task: {
      type: "ProsopoTokenProxyLess",
      websiteURL: "https://example.com/register",
      websiteKey: "5HGjXJPbERv4F..."
    }
  })
}).then(r => r.json());


while (true) {
  const result = await fetch("https://api.ucaptcha.net/getTaskResult", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: API_KEY, taskId })
  }).then(r => r.json());


  if (result.status === "ready") {
    console.log("Solution:", result.solution.token);
    break;
  } else if (result.status === "failed") {
    console.error("Error:", result.errorDescription);
    break;
  }
  await new Promise(r => setTimeout(r, 5000));
}
```

--------------------------------

### Solution Object (JSON)

Source: https://ucaptcha.net/docs/tasks/token/temu

Example solution object returned when the task is ready, containing the Temu verification token to submit with the request.

```json
{
  "token": "temu_verify_1a2b3c4d5e6f7g8h...token_value"
}
```

--------------------------------

### Python Example: Create Task and Poll for Solution

Source: https://ucaptcha.net/docs/tasks/token/prosopo

Python script using requests to create a ProsopoTokenProxyLess task, poll getTaskResult until ready, and submit the form with the token.

```python
import requests
import time


API_KEY = "YOUR_API_KEY"


response = requests.post("https://api.ucaptcha.net/createTask", json={
    "clientKey": API_KEY,
    "task": {
        "type": "ProsopoTokenProxyLess",
        "websiteURL": "https://example.com/register",
        "websiteKey": "5HGjXJPbERv4F..."
    }
})
task_id = response.json()["taskId"]


while True:
    result = requests.post("https://api.ucaptcha.net/getTaskResult", json={
        "clientKey": API_KEY,
        "taskId": task_id
    }).json()
    if result["status"] == "ready":
        token = result["solution"]["token"]
        print("Solution:", token)


        # Submit the form with the Procaptcha token
        form_data = {
            "procaptcha-response": token,
            "email": "user@example.com",
            "password": "securepassword"
        }
        response = requests.post("https://example.com/register", data=form_data)
        print("Status:", response.status_code)
        break
    elif result["status"] == "failed":
        print("Error:", result.get("errorDescription"))
        break
    time.sleep(5)
```

--------------------------------

### How to Use

Source: https://ucaptcha.net/docs/tasks/token/cloudflare-challenge

Steps to use the solution to bypass the Cloudflare challenge.

```APIDOC
## How to Use

### Description
Steps to use the solution to bypass the Cloudflare challenge.

### Steps
1. Submit the task and poll for the solution.
2. Set the `cf_clearance` cookie in your browser or HTTP client for the target domain.
3. Set the `User-Agent` header to the exact value returned in `solution.userAgent`.
4. Make your request to the protected URL. The Cloudflare challenge will be bypassed.

### Important

The `cf_clearance` cookie is bound to the User-Agent string. If you use a different User-Agent than the one returned in the solution, Cloudflare will reject the cookie and present the challenge again.
```

--------------------------------

### Error response example

Source: https://ucaptcha.net/docs/api/deathbycaptcha/submit

Example error response for invalid or missing authtoken. HTTP status 401 corresponds to this JSON body.

```json
{
  "status": 255,
  "error": "Invalid or missing authtoken"
}
```

--------------------------------

### Callback Request: GET with result parameters

Source: https://ucaptcha.net/docs/api/callbacks

uCaptcha sends a GET request to your callback URL with captcha_id, status, and code as query parameters.

```http
GET https://your-server.com/captcha-callback?captcha_id=TASK_ID&status=1&code=SOLUTION
```

--------------------------------

### TSPD Solution Object JSON Example

Source: https://ucaptcha.net/docs/tasks/token/tspd

Example of the solution object returned by the API, containing the TSPD verification token to submit with the request.

```json
{
  "token": "tspd_session_eyJhbGciOiJ...verification_payload"
}
```

--------------------------------

### cURL Example: Create PerimeterXToken Task

Source: https://ucaptcha.net/docs/tasks/token/perimeterx

cURL command to create a PerimeterXToken task using the createTask endpoint. Note: this example omits the proxy parameter.

```bash
curl -X POST https://api.ucaptcha.net/createTask \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "PerimeterXToken",
      "websiteURL": "https://example.com/protected-page"
    }
  }'
```

--------------------------------

### cURL example for /api/user

Source: https://ucaptcha.net/docs/api/deathbycaptcha/account

Use this cURL command to retrieve account balance. Replace YOUR_API_KEY with your actual API key.

```bash
curl -X POST https://api.ucaptcha.net/api/user \
  -d "authtoken=YOUR_API_KEY"
```

--------------------------------

### Kasada Token Solution Object Example

Source: https://ucaptcha.net/docs/tasks/token/kasada

Example of the solution object returned by the API, containing a token field with a ct=... cookie value for KasadaToken.

```json
{
  "token": "ct=abc123xyz..."
}
```

--------------------------------

### Python Example - Create and Poll Task

Source: https://ucaptcha.net/docs/tasks/token/hcaptcha

Python script using requests to create a HardCaptchaTokenProxyLess task and poll for the result. Prints token, respKey, and userAgent when ready.

```python
import requests
import time


API_KEY = "YOUR_API_KEY"


# Create task
response = requests.post("https://api.ucaptcha.net/createTask", json={
    "clientKey": API_KEY,
    "task": {
        "type": "HardCaptchaTokenProxyLess",
        "websiteURL": "https://example.com/signup",
        "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
    }
})
task_id = response.json()["taskId"]


# Poll for result
while True:
    result = requests.post("https://api.ucaptcha.net/getTaskResult", json={
        "clientKey": API_KEY,
        "taskId": task_id
    }).json()


    if result["status"] == "ready":
        solution = result["solution"]
        print("Token:", solution["token"])
        print("RespKey:", solution.get("respKey"))
        print("UserAgent:", solution.get("userAgent"))
        break
    elif result["status"] == "failed":
        print("Error:", result.get("errorDescription"))
        break


    time.sleep(5)
```

--------------------------------

### POST /x402/createTask with X-PAYMENT header

Source: https://ucaptcha.net/docs/features/x402-payments

Example request with a base64-encoded EIP-3009 transferWithAuthorization payload in the X-PAYMENT header. The body is a task object; the example shows a placeholder.

```http
POST /x402/createTask HTTP/1.1
Host: api.ucaptcha.net
Content-Type: application/json
X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiYmFzZSIsInBheWxvYWQiOnsiYXV0aG9yaXphdGlvbiI6eyJmcm9tIjoiMHguLi4iLCJ0byI6IjB4QURCQTQ5MmZiMmU0MTkxMmQ4MjE2MUM3RTViRkU0MTk1RTRjNjYzNyIsInZhbHVlIjoiMTIwMDAiLCJ2YWxpZEFmdGVyIjoiMCIsInZhbGlkQmVmb3JlIjoiOTk5OTk5OTk5OSIsIm5vbmNlIjoiMHguLi4ifSwic2lnbmF0dXJlIjoiMHguLi4ifX0=


{ "task": { "type": "HardCaptchaTokenProxyLess", "...": "..." } }
```

--------------------------------

### Full Flow Example (cURL)

Source: https://ucaptcha.net/docs/api/legacy/res-php

Complete cURL script that submits a task, polls for the result, and reports the solution quality.

```bash
# 1. Submit task
RESPONSE=$(curl -s "https://api.ucaptcha.net/in.php?key=YOUR_API_KEY&method=userrecaptcha&googlekey=SITE_KEY&pageurl=https://example.com&json=1")
TASK_ID=$(echo "$RESPONSE" | jq -r '.request')


# 2. Poll for result
while true; do
  RESULT=$(curl -s "https://api.ucaptcha.net/res.php?key=YOUR_API_KEY&action=get&id=$TASK_ID&json=1")
  STATUS=$(echo "$RESULT" | jq -r '.status')


  if [ "$STATUS" = "1" ]; then
    echo "Solution: $(echo "$RESULT" | jq -r '.request')"
    break
  fi


  REQUEST=$(echo "$RESULT" | jq -r '.request')
  if [ "$REQUEST" != "CAPCHA_NOT_READY" ]; then
    echo "Error: $REQUEST"
    break
  fi


  sleep 5
done


# 3. Report result quality
curl -s "https://api.ucaptcha.net/res.php?key=YOUR_API_KEY&action=reportgood&id=$TASK_ID"
```

--------------------------------

### GeeTest v4 Solution Object

Source: https://ucaptcha.net/docs/tasks/token/geetest-v4

Example solution object returned after task completion. Contains five fields: captcha_id, lot_number, pass_token, gen_time, and captcha_output. All fields are required for verification.

```json
{
  "captcha_id": "e392e1d7fd421dc63325744d5a2b9c73",
  "lot_number": "7005867dc6a20f02bc79c78284a1e8ab",
  "pass_token": "fdc26eb58cf4a4f6abe3ddbddcc32a560a30b...",
  "gen_time": "1709123456",
  "captcha_output": "dWsBX4E7JiIvJBkABn..."
}
```

--------------------------------

### Robust Error Handling Example

Source: https://ucaptcha.net/docs/api/error-codes

A complete example of solving a captcha with error handling. It creates a task, polls for the result, and raises exceptions for request errors, task failures, and timeouts.

```python
import requests
import time


def solve_captcha(client_key, task):
    # Create task
    create_resp = requests.post("https://api.ucaptcha.net/createTask", json={
        "clientKey": client_key,
        "task": task
    }).json()


    if create_resp["errorId"] != 0:
        raise Exception(f"Create failed: {create_resp['errorCode']}")


    task_id = create_resp["taskId"]


    # Poll for result
    for _ in range(60):
        result_resp = requests.post("https://api.ucaptcha.net/getTaskResult", json={
            "clientKey": client_key,
            "taskId": task_id
        }).json()


        if result_resp["errorId"] != 0:
            raise Exception(f"Poll failed: {result_resp['errorCode']}")


        if result_resp["status"] == "ready":
            return result_resp["solution"]


        if result_resp["status"] == "failed":
            raise Exception(f"Task failed: {result_resp.get('errorCode', 'unknown')}")


        time.sleep(5)


    raise TimeoutError("Task did not complete within 5 minutes")
```

--------------------------------

### cURL Example with x-api-key Header

Source: https://ucaptcha.net/docs/api/riskbypass/balance

cURL command to retrieve the balance using the x-api-key header for authentication. Replace YOUR_API_KEY with your actual API key.

```bash
curl -X POST https://api.ucaptcha.net/api/user/balance \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Response from /createTask

Source: https://ucaptcha.net/docs

Example JSON response from /createTask containing errorId and taskId.

```json
{
  "errorId": 0,
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

--------------------------------

### Error Response

Source: https://ucaptcha.net/docs/api/overview

Example error response with errorId 1 and error code.

```json
{
  "errorId": 1,
  "errorCode": "ERROR_KEY_DOES_NOT_EXIST",
  "errorDescription": "The API key you provided does not exist in our system."
}
```

--------------------------------

### Python - Create and Poll TextCaptchaTask

Source: https://ucaptcha.net/docs/tasks/recognition/text-captcha

Python example using requests to create a TextCaptchaTask and poll for the result. Prints the answer when ready or an error if failed.

```python
import requests


API_KEY = "YOUR_API_KEY"


response = requests.post("https://api.ucaptcha.net/createTask", json={
    "clientKey": API_KEY,
    "task": {
        "type": "TextCaptchaTask",
        "comment": "What color is the sky?"
    }
}).json()


if response.get("status") == "ready":
    print("Answer:", response["solution"]["text"])
else:
    import time
    task_id = response["taskId"]
    while True:
        result = requests.post("https://api.ucaptcha.net/getTaskResult", json={
            "clientKey": API_KEY,
            "taskId": task_id
        }).json()


        if result["status"] == "ready":
            print("Answer:", result["solution"]["text"])
            break
        elif result["status"] == "failed":
            print("Error:", result.get("errorDescription"))
            break


        time.sleep(5)
```

--------------------------------

### Error response

Source: https://ucaptcha.net/docs/api/riskbypass/submit

Example error response with ok false and an error message.

```json
{
  "ok": false,
  "error": "Unsupported task_type: unknown_type"
}
```
Tokens:
Raw