Skip to content

Quick Start

This guide walks you through solving a reCAPTCHA v2 task using the uCaptcha API. The same pattern applies to all supported CAPTCHA types.

  1. Get your API key

    Open @uCaptcha_bot on Telegram. Your account is created automatically on first interaction, and an API key (prefixed with ucap_) is generated for you. You can manage keys later in the Telegram Mini App under the API tab.

  2. Create a task

    Send a POST request to /createTask with your CAPTCHA parameters.

    Python:

    import requests
    import time
    

    API_KEY = "YOUR_API_KEY"
    

    # Step 1: Create task
    response = requests.post("https://api.ucaptcha.net/createTask", json={
        "clientKey": API_KEY,
        "task": {
            "type": "ReCaptchaV2TokenProxyLess",
            "websiteURL": "https://example.com",
            "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
        }
    })
    task_id = response.json()["taskId"]

    JavaScript:

    const API_KEY = "YOUR_API_KEY";
    

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

    cURL:

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

    The response contains a taskId that you use to retrieve the result:

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

  3. Poll for the result

    Send requests to /getTaskResult every 5 seconds until status is "ready" or "failed".

    Python:

    # Step 2: 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":
            print("Token:", result["solution"]["gRecaptchaResponse"])
            break
        elif result["status"] == "failed":
            print("Error:", result.get("errorDescription"))
            break
    

        time.sleep(5)

    JavaScript:

    // Step 2: Poll for result
    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.gRecaptchaResponse);
        break;
      } else if (result.status === "failed") {
        console.error("Error:", result.errorDescription);
        break;
      }
    

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

    cURL:

    Terminal window
    curl -X POST https://api.ucaptcha.net/getTaskResult \
      -H "Content-Type: application/json" \
      -d '{
        "clientKey": "YOUR_API_KEY",
        "taskId": "TASK_ID_FROM_STEP_2"
      }'

    The ready response looks like:

    {
      "errorId": 0,
      "status": "ready",
      "solution": {
        "gRecaptchaResponse": "03AGdBq24PBCbwiDRaS_MJ7Z..."
      }
    }

  4. Use the solution

    When status is "ready", the solution object contains your token. Submit it to the target website’s form or API as the g-recaptcha-response parameter. The exact field name varies by CAPTCHA type — see the task type documentation for details.

[!TIP] Use a 5-second polling interval. Polling faster does not speed up solving and may trigger rate limits.

Legacy API (2captcha compatible)

Section titled “Legacy API (2captcha compatible)”

Already using 2captcha? Just swap the base URL. No other code changes needed:

https://2captcha.com/in.php
https://api.ucaptcha.net/in.php


https://2captcha.com/res.php
https://api.ucaptcha.net/res.php

Your existing key parameter, task parameters, and response parsing all remain the same.

What’s Next?

Section titled “What’s Next?”