Getting Started with Friendly Captcha and the CaptchaAI API

If you've been looking for a clean, modern way to bypass Friendly Captcha — the privacy-first proof-of-work CAPTCHA — you're in the right place. In this short blog post, we'll go from zero to a working solution in just a few minutes using the CaptchaAI API.

No long setup. No boilerplate. Just the parts you actually need.

What is Friendly Captcha?

Friendly Captcha is a privacy-friendly CAPTCHA alternative. Instead of forcing users to click images or type distorted text, it asks the browser to solve a small proof-of-work puzzle before the form can be submitted. The result is a single token that you submit with your form.

You'll typically see it as:

A widget embedded directly in a form
A <div class="frc-captcha"> container in the DOM
A token returned in the frc-captcha-solution field

Prerequisites

Before we start, make sure you have:

A CaptchaAI account — sign up at captchaai.com.
Your API key from the dashboard.
A positive balance (or contact support for a free trial).
Python 3 with the requests library installed (or any HTTP client you like).

That's it. Let's go.

Step 1 — Find the Sitekey

Open the page that contains the Friendly Captcha widget and inspect the DOM. Look for an element like this:

<div class="frc-captcha" data-sitekey="FCMGEMUD2M567T8G" data-start="auto"></div>

Grab two things from it:

The data-sitekey value → e.g. FCMGEMUD2M567T8G
The full page URL where the widget lives

Step 2 — Submit the Task to CaptchaAI

Send a GET request to https://ocr.captchaai.com/in.php with the friendly_captcha method:

import requests

params = {
    'key': 'YOUR_API_KEY',
    'method': 'friendly_captcha',
    'pageurl': 'https://example.com/login',
    'sitekey': 'FCMGEMUD2M567T8G',
    'json': '1'
}

response = requests.get('https://ocr.captchaai.com/in.php', params=params)
result = response.json()
task_id = result['request']
print('Task ID:', task_id)

You'll get a response like:

{ "status": 1, "request": "74965409378" }

That request value is your task ID. Save it.

Step 3 — Poll for the Solution

Friendly Captcha solves fast, but give it a few seconds. Then poll res.php:

import time, requests

time.sleep(15)

params = {
    'key': 'YOUR_API_KEY',
    'action': 'get',
    'id': task_id,
    'json': '1'
}

result = requests.get('https://ocr.captchaai.com/res.php', params=params).json()

if result['status'] == 1:
    token = result['request']
    print('Token:', token)

The request value is your Friendly Captcha token — a long base64-ish string. It looks like:

72b43902cd1457f6880dd3735c50070d.Z0+9+Hcx7KGSmHd1AQwtjQ...

Step 4 — Inject the Token

Before submitting the form, inject the token into the frc-captcha-solution field. Here's a small, defensive snippet you can drop into your browser automation:

(token) => {
  const widget = document.querySelector('.frc-captcha');
  const fieldName = widget?.getAttribute('data-solution-field-name') || 'frc-captcha-solution';
  const form = widget?.closest('form') || document.querySelector('form') || document.body;

  let input = form.querySelector(`input[name="${fieldName}"]`);
  if (!input) {
    input = document.createElement('input');
    input.type = 'hidden';
    input.name = fieldName;
    form.appendChild(input);
  }

  input.value = token;
  input.dispatchEvent(new Event('input', { bubbles: true }));
  input.dispatchEvent(new Event('change', { bubbles: true }));

  return { ok: true, fieldName };
}

Submit the form, and you're in.

Common Pitfalls (and how to avoid them)

Wrong pageurl — Always use the exact URL where the widget renders, including query strings.
Stale sitekey — Read data-sitekey from the live DOM, not from a cached page.
CAPCHA_NOT_READY — Just means the solver is still working. Wait 5–10 seconds and poll again.

For the full list of error codes, see the Error Handling Guide.

A Few Pro Tips

Tip: If the page exposes data-solution-field-name, use that — some sites override the default field name.

Tip: Friendly Captcha tokens are short-lived. Don't cache them; inject them right before submission.

Tip: If you're running at scale, rotate your pageurl and sitekey per session to mimic natural traffic.

Wrapping Up

That's the whole loop: find the sitekey → submit the task → poll for the token → inject it. Once you have the pattern down, Friendly Captcha is one of the simpler CAPTCHA types to automate.

For the full API reference, head over to the CaptchaAI API Docs and select Friendly Captcha from the sidebar.

Happy solving!