1. Authentication

Include the Authorization: Bearer YOUR_API_KEY header in every request.

# Required headers
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

2. Solve an HCaptcha Image Task

POST /v2/solver/hcaptcha/image

Request Body

{
  "images": [
    "base64_encoded_image_1",   // required — list of base64-encoded images
    "base64_encoded_image_2"
  ],
  "question": "Please click each image containing a bus",  // optional
  "priority": "balanced"        // "speed" | "balanced" | "accuracy"
}

Response

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "estimated_time": 15.0,
  "message": "Task submitted successfully"
}

CURL Example

curl -X POST "https://api.smartcaptcha.com/v2/solver/hcaptcha/image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["'"$(base64 -w0 captcha.png)"'"],
    "question": "Please click each image containing a bus",
    "priority": "balanced"	
  }'

Python Example

import requests, base64

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.smartcaptcha.com/v2"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Convert image to base64
with open("captcha.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

payload = {
    "images": [img_b64],
    "question": "Please click each image containing a bus",
    "priority": "balanced"   # "speed" | "balanced" | "accuracy"
}

response = requests.post(f"{BASE_URL}/solver/hcaptcha/image", headers=headers, json=payload)
task_id = response.json()["task_id"]
print(f"Task created: {task_id}")

3. Solve a ReCaptcha V2 Task

POST /v2/solver/recaptcha/v2

Request Body

{
  "site_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",  // required
  "page_url": "https://example.com/login",                  // required
  "data_s": "optional_data_s_token",                        // optional
  "priority": "balanced"                                    // "speed" | "balanced" | "accuracy"
}

Response

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "estimated_time": 20.0,
  "message": "ReCaptcha V2 task submitted"
}

Python Example

payload = {
    "site_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    "page_url": "https://example.com/login",
    "priority": "balanced"
}

response = requests.post(f"{BASE_URL}/solver/recaptcha/v2", headers=headers, json=payload)
task_id = response.json()["task_id"]
print(f"ReCaptcha task created: {task_id}")

4. Retrieve Task Result

GET /v2/solver/result/{task_id}

Response — HCaptcha (completed)

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",        // "pending" | "processing" | "completed" | "failed"
  "captcha_type": "HcaptchaImageTask",
  "coordinates": [              // click coordinates returned for HCaptcha tasks
    {"x": 120, "y": 85},
    {"x": 340, "y": 210}
  ],
  "verify": "P1_eyJ0...",       // verify token (if available)
  "bounding_box": null,
  "processing_time": null,
  "credits_used": 0.15,
  "error": null
}

Response — Failed Task

{
  "task_id": "a1b2c3d4-...",
  "status": "failed",
  "captcha_type": null,
  "coordinates": null,
  "verify": null,
  "bounding_box": null,
  "processing_time": null,
  "credits_used": null,
  "error": "Insufficient credits. Need 0.15, have 0.05"
}

Python — Polling Example

import time

def get_result(task_id, timeout=60):
    for _ in range(timeout // 5):
        res = requests.get(
            f"{BASE_URL}/solver/result/{task_id}",
            headers=headers
        ).json()

        if res["status"] == "completed":
            print("Coordinates:", res["coordinates"])
            print("Verify token:", res.get("verify"))
            print("Credits used:", res["credits_used"])
            return res

        elif res["status"] == "failed":
            raise Exception(f"Task failed: {res['error']}")

        time.sleep(5)   # Retry after 5 seconds

    raise TimeoutError("Task timed out")

result = get_result(task_id)

5. List Your Tasks

GET /v2/solver/tasks?limit=50&offset=0&status=completed

Query parameters: limit (1–100, default 50), offset (default 0), status (optional filter).

Response

{
  "total": 142,
  "limit": 50,
  "offset": 0,
  "tasks": [
    {
      "task_id": "a1b2c3d4-...",
      "status": "completed",
      "captcha_type": "HcaptchaImageTask",
      "credits_used": 0.15,
      "created_at": "2024-06-01T12:00:00Z"
    }
    // ...additional tasks
  ]
}

Python Example

# Fetch only completed tasks, page 2
params = {"limit": 20, "offset": 20, "status": "completed"}
tasks = requests.get(f"{BASE_URL}/solver/tasks", headers=headers, params=params).json()
print(f"Total: {tasks['total']}, fetched: {len(tasks['tasks'])}")

6. Delete a Task

DELETE /v2/solver/task/{task_id}

Only completed or failed tasks can be deleted. Tasks currently being processed cannot be removed.

Response

{
  "message": "Task deleted successfully",
  "task_id": "a1b2c3d4-..."
}

Python Example

res = requests.delete(
    f"{BASE_URL}/solver/task/{task_id}",
    headers=headers
)
print(res.json()["message"])

7. View Pricing

GET /v2/solver/pricing (No authentication required)

Response

{
  "pricing": [
    {
      "task_type": "HcaptchaImageTask",
      "speed":    0.10,   // credits per task
      "balanced": 0.15,
      "accuracy": 0.25
    },
    {
      "task_type": "RecaptchaV2Task",
      "speed":    0.20,
      "balanced": 0.30,
      "accuracy": 0.40
    },
    {
      "task_type": "RecaptchaV3Task",
      "speed":    0.25,
      "balanced": 0.35,
      "accuracy": 0.50
    }
  ],
  "note": "Prices in credits per task. 1 credit = $0.01 USD"
}

CURL Example

curl "https://api.smartcaptcha.com/v2/solver/pricing"

8. Common Error Codes

400  Bad Request       — Invalid request body or parameters
401  Unauthorized      — API key is missing or invalid
402  Payment Required  — Insufficient credits
    {
      "detail": "Insufficient credits. Need 0.15, have 0.05"
    }
404  Not Found         — Task ID does not exist or does not belong to you
500  Server Error      — Internal server error