Getting Started

Authentication

Every request requires an X-API-Key header with your API key. Get one from the dashboard.

X-API-Key: oc_your_api_key_here

Base URL

https://api.one-captcha.com

Sync vs Async Solving

Every SDK provides two ways to solve captchas. Use whichever fits your workflow.

// Node.js
const r = await client.solveRecaptchaV2({
  url, sitekey
});
console.log(r.token);

// Node.js — automatic polling
const r = await client.solveRecaptchaV2Async({
  url, sitekey
});
console.log(r.token);

Every solve* method has a matching solve*Async variant. Both return the same result shape.

Sync Solve Examples

curl -X POST https://api.one-captcha.com/v1/solve \
  -H "X-API-Key: oc_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "recaptcha_v2",
    "params": {
      "url": "https://example.com",
      "sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
    }
  }'

// ESM
import { OneCaptchaClient } from '@onecaptcha/sdk';
// or CommonJS
// const { OneCaptchaClient } = require('@onecaptcha/sdk');

const client = new OneCaptchaClient({ apiKey: 'oc_your_key' });

const r = await client.solveRecaptchaV2({
  url: 'https://example.com',
  sitekey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
});
console.log(r.token);
await r.reportGood(); // tell the gateway it worked

// Image OCR — just pass the base64 string
const img = await client.solveImageToText(base64);
console.log(img.text);
await img.reportGood();

from onecaptcha import OneCaptchaClient, RecaptchaV2
client = OneCaptchaClient(api_key="oc_your_key")

result = client.solve(RecaptchaV2(
    url="https://example.com",
    sitekey="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
))
print(result.token)

client := onecaptcha.New("oc_your_key")

result, err := client.Solve(ctx, onecaptcha.RecaptchaV2{
    URL:     "https://example.com",
    SiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
fmt.Println(result.Token)

var client = OneCaptchaClient.builder()
    .apiKey("oc_your_key").build();

var result = client.solve(SolveRequest.RecaptchaV2.of(
    "https://example.com",
    "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
));
System.out.println(result.token());

onecaptcha::OneCaptchaClient client({.apiKey = "oc_your_key"});

auto result = client.solve(onecaptcha::RecaptchaV2{
    .url     = "https://example.com",
    .sitekey = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
std::cout << result.token << std::endl;

var client = try oc.Client.init(allocator, io,
    .{ .api_key = "oc_your_key" });

const outcome = try client.solve(oc.RecaptchaV2{
    .url = "https://example.com",
    .sitekey = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
}, .{});
std.debug.print("{s}\n", .{outcome.result().token});

Response

{
  "type": "recaptcha_v2",
  "status": "ready",
  "taskRef": "550e8400-e29b-41d4-a716-446655440000",
  "token": "03AGdBq24PBCbwiDRaS_MJ7Z...",
  "cost": 0.002990
}

Every response includes a taskRef (UUID) you can use to report whether the solution worked. See Reporting below.

Async Solve Examples

Every solve* method has a matching solve*Async that submits the task and polls until ready. You can also use createTask + waitForTask for manual control over the polling loop.

import { OneCaptchaClient } from '@onecaptcha/sdk';
const client = new OneCaptchaClient({ apiKey: 'oc_your_key' });

// Per-type async helper — submits + polls automatically
const result = await client.solveRecaptchaV2Async({
  url: 'https://example.com',
  sitekey: '6Le-wvk...',
});
console.log(result.token);
await result.reportGood(); // report success

// Image OCR async
const img = await client.solveImageToTextAsync(base64);
console.log(img.text);
await img.reportGood();

from onecaptcha import OneCaptchaClient, RecaptchaV2
client = OneCaptchaClient(api_key="oc_your_key")

result = client.solve_async(RecaptchaV2(
    url="https://example.com",
    sitekey="6Le-wvk...",
))
print(result.token)

client := onecaptcha.New("oc_your_key")

result, err := client.SolveAsync(ctx, onecaptcha.RecaptchaV2{
    URL: "https://example.com",
    SiteKey: "6Le-wvk...",
})
fmt.Println(result.Token)

var client = OneCaptchaClient.builder()
    .apiKey("oc_your_key").build();

var result = client.solveAsync(
    SolveRequest.RecaptchaV2.of(
        "https://example.com", "6Le-wvk..."));
System.out.println(result.token());

onecaptcha::OneCaptchaClient client({.apiKey = "oc_your_key"});

auto result = client.solveAsync(
    RecaptchaV2{.url = "https://example.com",
                .sitekey = "6Le-wvk..."});
std::cout << result.token << std::endl;

var client = try oc.Client.init(allocator, io,
    .{ .api_key = "oc_your_key" });

const outcome = try client.solveAsync(oc.RecaptchaV2{
    .url = "https://example.com",
    .sitekey = "6Le-wvk...",
}, .{});
std.debug.print("{s}\n", .{outcome.result().token});

Reporting

After using the solution on the target site, report whether it was accepted. This helps providers flag bad workers and may trigger refunds. For image_to_text solves, a good report promotes the result into the permanent image cache so future identical images resolve instantly.

Every result object carries reportGood() / reportBad() helpers so you can report directly without tracking the taskRef yourself.

# Report that the solution worked
curl -X POST https://api.one-captcha.com/v1/tasks/550e8400-e29b-41d4-a716-446655440000/report \
  -H "X-API-Key: oc_your_key" \
  -H "Content-Type: application/json" \
  -d '{"accepted": true}'

# Report that the solution was rejected
curl -X POST https://api.one-captcha.com/v1/tasks/550e8400-e29b-41d4-a716-446655440000/report \
  -H "X-API-Key: oc_your_key" \
  -H "Content-Type: application/json" \
  -d '{"accepted": false}'

const result = await client.solveRecaptchaV2({ url, sitekey });

// Use the token on the target site, then:
await result.reportGood();   // solution worked
await result.reportBad();    // solution was rejected

// Standalone helpers:
await client.reportGood(result.taskRef);
await client.reportBad(result.taskRef);

result = client.solve(RecaptchaV2(url=url, sitekey=sitekey))

# Report directly from the result:
result.report_good()   # target accepted the token
result.report_bad()    # target rejected the token

# Or standalone:
client.report_good(result.task_ref)
client.report_bad(result.task_ref)

result, _ := client.Solve(ctx, onecaptcha.RecaptchaV2{URL: url, SiteKey: sitekey})

// Report directly from the result:
result.ReportGood(ctx)   // target accepted the token
result.ReportBad(ctx)    // target rejected the token

// Or standalone:
client.ReportGood(ctx, result.TaskRef)
client.ReportBad(ctx, result.TaskRef)

var result = client.solve(SolveRequest.RecaptchaV2.of(url, sitekey));

// Report directly from the result:
result.reportGood().run();   // target accepted the token
result.reportBad().run();    // target rejected the token

// Or standalone:
client.reportGood(result.taskRef());
client.reportBad(result.taskRef());

Other Endpoints

Captcha Type Reference

Each type uses the same POST /v1/solve endpoint. Pass the type and its required params.

{
  "type": "recaptcha_v2",
  "params": {
    "url": "https://example.com/page",
    "sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    "invisible": false
  }
}

{
  "type": "recaptcha_v2_enterprise",
  "params": { "url": "...", "sitekey": "...", "invisible": false }
}

{
  "type": "recaptcha_v3",
  "params": {
    "url": "https://example.com",
    "sitekey": "6LdKlZEpAAAAAN...",
    "action": "login",
    "minScore": 0.7
  }
}

{
  "type": "funcaptcha",
  "params": {
    "url": "https://example.com",
    "publicKey": "DE0B0BB7-1EE4-4D70-1853-31B835D4506B",
    "subdomain": "client-api.arkoselabs.com"
  }
}

{
  "type": "turnstile",
  "params": {
    "url": "https://example.com",
    "sitekey": "0x4AAAAAAABS7vwvV6VFfMcD"
  }
}

{
  "type": "geetest_v3",
  "params": {
    "url": "https://example.com",
    "gt": "022f3a3f52b2b1f1...",
    "challenge": "a]66d..."
  }
}

{
  "type": "geetest_v4",
  "params": {
    "url": "https://example.com",
    "captchaId": "e392e1d7fd421dc63325744d5a2b9c73"
  }
}

{
  "type": "amazon_waf",
  "params": {
    "url": "https://example.com",
    "key": "AQIDAHjcYu/GjX+QlghicBg..."
  }
}

{
  "type": "mtcaptcha",
  "params": { "url": "https://example.com", "sitekey": "MTPublic-..." }
}

{
  "type": "image_to_text",
  "params": {
    "body": "/9j/4AAQSkZJRg...",
    "caseSensitive": true,
    "numeric": 0,
    "minLength": 4,
    "maxLength": 8
  }
}

// Simple — just pass the base64 string
const result = await client.solveImageToText(base64Image);
console.log(result.text);

// With options
const result = await client.solveImageToText({
  body: base64Image,
  caseSensitive: true,
  minLength: 4,
});

// Async
const result = await client.solveImageToTextAsync(base64Image);

{
  "type": "image_to_coordinates",
  "params": {
    "body": "/9j/4AAQSkZJRg...",
    "comment": "Click all traffic lights",
    "mode": "points"
  }
}