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 Solve

POST /v1/solve — Submits and waits for the solution in a single request. Best for most use cases.

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-"
    }
  }'

import { OneCaptchaClient } from '@onecaptcha/sdk';

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

const result = await client.solveRecaptchaV2({
  url: 'https://example.com',
  sitekey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
});

console.log(result.token);

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)

package main

import (
    "context"
    "fmt"
    "onecaptcha"
)

func main() {
    client := onecaptcha.New("oc_your_key")

    result, err := client.Solve(context.Background(), onecaptcha.RecaptchaV2{
        URL:     "https://example.com",
        SiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(result.Token)
}

import com.onecaptcha.sdk.*;

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());

#include "onecaptcha/onecaptcha.hpp"

int main() {
    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;
}

const oc = @import("onecaptcha");

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-",
    }, .{},
);

const result = outcome.result();
std.debug.print("{s}\n", .{result.token});

Response

{
  "type": "recaptcha_v2",
  "status": "ready",
  "provider": "capsolver",
  "token": "03AGdBq24PBCbwiDRaS_MJ7Z...",
  "cost": 0.002990
}

Async Solve (Submit + Poll)

For long-running captchas or when you want to control the polling loop yourself. All SDKs provide both a manual submit/poll flow and a convenience solveAsync that handles polling for you.

REST API

1. Submit: POST /v1/tasks — same body as /v1/solve

// Returns: { "status": "processing", "taskRef": "v1.eyJ..." }

2. Poll: GET /v1/tasks/{taskRef}

// Returns: { "status": "processing" } or { "status": "ready", "token": "..." }

3. Report: POST /v1/tasks/{taskRef}/report

{ "accepted": false }

SDK Examples

Every SDK wraps the submit/poll loop. Use solveAsync for automatic polling, or createTask + getTask / waitForTask for manual control.

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

// Option 1: solveAsync — submits + polls automatically
const result = await client.solveAsync({
  type: 'recaptcha_v2',
  params: { url: 'https://example.com', sitekey: '6Le-wvk...' },
}, { pollInterval: 3000, pollTimeout: 120000 });

console.log(result.token);

// Option 2: manual submit + poll
const task = await client.createTask({
  type: 'recaptcha_v2',
  params: { url: 'https://example.com', sitekey: '6Le-wvk...' },
});
console.log('Submitted:', task.taskRef);

// Poll until ready
const ready = await client.waitForTask(task.taskRef, {
  pollInterval: 3000,
  pollTimeout: 120000,
});
console.log(ready.token);

// Report bad solution
await client.reportTask(task.taskRef, false);

from onecaptcha import OneCaptchaClient, RecaptchaV2, WaitOptions

client = OneCaptchaClient(api_key="oc_your_key")

# Option 1: solve_async — submits + polls automatically
result = client.solve_async(
    RecaptchaV2(url="https://example.com", sitekey="6Le-wvk..."),
    WaitOptions(poll_interval_sec=3, poll_timeout_sec=120),
)
print(result.token)

# Option 2: manual submit + poll
task = client.create_task(
    RecaptchaV2(url="https://example.com", sitekey="6Le-wvk...")
)
print(f"Submitted: {task.task_ref}")

ready = client.wait_for_task(
    task.task_ref,
    WaitOptions(poll_interval_sec=3, poll_timeout_sec=120),
)
print(ready.token)

# Report bad solution
client.report_task(task.task_ref, accepted=False)

package main

import (
    "context"
    "fmt"
    "time"
    "onecaptcha"
)

func main() {
    client := onecaptcha.New("oc_your_key")
    ctx := context.Background()

    // Option 1: SolveAsync — submits + polls automatically
    result, err := client.SolveAsync(ctx, onecaptcha.RecaptchaV2{
        URL: "https://example.com", SiteKey: "6Le-wvk...",
    }, onecaptcha.WithWaitInterval(3*time.Second),
       onecaptcha.WithWaitTimeout(120*time.Second))

    // Option 2: manual submit + poll
    task, _ := client.CreateTask(ctx, onecaptcha.RecaptchaV2{
        URL: "https://example.com", SiteKey: "6Le-wvk...",
    })
    fmt.Println("Submitted:", task.TaskRef)

    ready, _ := client.WaitForTask(ctx, task.TaskRef,
        onecaptcha.WithWaitInterval(3*time.Second))
    fmt.Println(ready.Token)

    // Report bad solution
    _ = client.ReportTask(ctx, task.TaskRef, false)
}

import com.onecaptcha.sdk.*;
import java.time.Duration;

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

// Option 1: solveAsync — submits + polls automatically
var result = client.solveAsync(
    SolveRequest.RecaptchaV2.of(
        "https://example.com", "6Le-wvk..."),
    new WaitOptions(Duration.ofSeconds(3),
        Duration.ofSeconds(120))
);
System.out.println(result.token());

// Option 2: manual submit + poll
var task = client.createTask(
    SolveRequest.RecaptchaV2.of(
        "https://example.com", "6Le-wvk..."));
System.out.println("Submitted: " + task.taskRef());

var ready = client.waitForTask(task.taskRef(),
    new WaitOptions(Duration.ofSeconds(3),
        Duration.ofSeconds(120)));
System.out.println(ready.token());

// Report bad solution
client.reportTask(task.taskRef(), false);

#include "onecaptcha/onecaptcha.hpp"
using namespace onecaptcha;

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

// Option 1: solveAsync — submits + polls automatically
auto result = client.solveAsync(
    RecaptchaV2{.url = "https://example.com", .sitekey = "6Le-wvk..."},
    {.pollInterval = std::chrono::seconds(3),
     .pollTimeout  = std::chrono::seconds(120)});

// Option 2: manual submit + poll
auto task = client.createTask(
    RecaptchaV2{.url = "https://example.com", .sitekey = "6Le-wvk..."});
std::cout << "Submitted: " << task.taskRef << std::endl;

auto ready = client.waitForTask(task.taskRef,
    {.pollInterval = std::chrono::seconds(3)});
std::cout << ready.token << std::endl;

// Report bad solution
client.reportTask(task.taskRef, false);

const onecaptcha = @import("onecaptcha");

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

// Option 1: solveAsync — submits + polls automatically
const result = try client.solveAsync(
    onecaptcha.RecaptchaV2{
        .url = "https://example.com", .sitekey = "6Le-wvk...",
    },
    .{ .poll_interval_ms = 3000, .poll_timeout_ms = 120000 });

// Option 2: manual submit + poll
const task = try client.createTask(
    onecaptcha.RecaptchaV2{
        .url = "https://example.com", .sitekey = "6Le-wvk...",
    });

const ready = try client.waitForTask(
    task.result().task_ref,
    .{ .poll_interval_ms = 3000 });

// Report bad solution
try client.reportTask(task.result().task_ref, false);

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
  }
}

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