Captcha Solver API Quickstart in 5 Minutes
This captcha solver API quickstart takes you from zero to your first solved captcha in about five minutes. You will sign up, grab an API key, send a createTask request, poll getTaskResult until the status is ready, and read the solution. Every code sample below matches the confirmed OMOCaptcha API V2 contract, so you can copy, paste, and run it against real endpoints today.
The whole flow is just two HTTP calls against the OMOCaptcha API (https://api.omocaptcha.com/v2). If you can send a POST request, you already know enough to finish this captcha API tutorial and solve captcha challenges from your own code.
Step 1: Sign Up and Grab Your Captcha Solver API Key
Create an account at OMOCaptcha (https://omocaptcha.com/en?utm_source=blog&utm_medium=organic). Every new account gets 1000 free solves, which is more than enough to complete this guide and test your integration end to end.
After signing up, open your dashboard and copy your API key (the clientKey). Keep it server-side; never expose it in front-end JavaScript or commit it to a public repo. If your success rate ever drops below 95%, OMOCaptcha issues a full refund, so testing costs you nothing.
Step 2: POST createTask
You create a task by POSTing to /createTask. The body always has two parts: your clientKey and a task object whose type decides what gets solved.
A successful response looks like this:
response = dict(errorId=0, errorCode="", errorDescription="", taskId="abc-123")
The HTTP status is always 200. Success or failure is decided by errorId: 0 means success, anything else is an error described in errorCode and errorDescription (the standard two-step createTask/getTaskResult envelope).
The simplest example: ImageToTextTask
The easiest way to get your first captcha solve is a plain image-to-text (OCR) task. Send the image as a base64 string:
payload = dict(
clientKey="YOUR_API_KEY",
task=dict(
type="ImageToTextTask",
imageBase64="iVBORw0KGgoAAAANS..."
)
)
The solution comes back as solution.text.
The token example: RecaptchaV2TokenTask
For reCAPTCHA v2 you do not send an image. You send the target page URL and its site key, and you receive a token:
payload = dict(
clientKey="YOUR_API_KEY",
task=dict(
type="RecaptchaV2TokenTask",
websiteURL="https://example.com/login",
websiteKey="6Lc_aXk..."
)
)
The solution arrives in solution.gRecaptchaResponse, which you submit into the target form exactly as a real user's token would be.
Step 3: Poll getTaskResult until ready
Solving is asynchronous. After you get a taskId, POST it to /getTaskResult and check status. There are exactly three statuses:
status - meaning - what to do
processing - still being solved - wait, then poll again
ready - solved - read solution
fail - could not be solved - stop; balance is refunded
Poll politely with a short backoff (average solve time is 0.42s, so start after ~2 seconds). On fail, OMOCaptcha refunds the charge to the same bucket it came from (balance, then voucher balance, then package).
Note on key-binding: a task is locked to the API key that created it. If you poll with a different key you get ERROR_TASK_KEY_MISMATCH. Always use the same clientKey for createTask and getTaskResult.
Step 4: Read the solution
Once status is ready, read the field that matches your task type: solution.text for OCR, solution.gRecaptchaResponse for reCAPTCHA/hCaptcha tokens, or solution.token for other token types. That is the complete createTask / getTaskResult loop.
Full code examples
This example signs a task, polls with backoff, and passes an HTTP timeout. Swap in your own key and image.
Python (requests)
import base64
import time
import requests
BASE = "https://api.omocaptcha.com/v2"
KEY = "YOUR_API_KEY"
def solve_image(path):
with open(path, "rb") as f:
img = base64.b64encode(f.read()).decode()
task = dict(type="ImageToTextTask", imageBase64=img)
payload = dict(clientKey=KEY, task=task)
r = requests.post(BASE + "/createTask", json=payload, timeout=30).json()
if r["errorId"] != 0:
raise RuntimeError(str(r["errorCode"]) + ": " + str(r["errorDescription"]))
task_id = r["taskId"]
delay = 2
for _ in range(20):
time.sleep(delay)
poll_payload = dict(clientKey=KEY, taskId=task_id)
res = requests.post(BASE + "/getTaskResult", json=poll_payload, timeout=30).json()
if res["errorId"] != 0:
raise RuntimeError(res["errorDescription"])
if res["status"] == "ready":
return res["solution"]["text"]
if res["status"] == "fail":
raise RuntimeError("solve failed (refunded)")
delay = min(delay + 1, 5) # gentle backoff
raise TimeoutError("no result in time")
print(solve_image("captcha.png"))
For a token captcha such as reCAPTCHA v2, reuse the same pattern: swap the task dict and read the token out of solution instead of solution.text.
def solve_recaptcha(url, sitekey):
task = dict(type="RecaptchaV2TokenTask", websiteURL=url, websiteKey=sitekey)
payload = dict(clientKey=KEY, task=task)
r = requests.post(BASE + "/createTask", json=payload, timeout=30).json()
if r["errorId"] != 0:
raise RuntimeError(r["errorDescription"])
task_id = r["taskId"]
delay = 2
for _ in range(20):
time.sleep(delay)
poll_payload = dict(clientKey=KEY, taskId=task_id)
res = requests.post(BASE + "/getTaskResult", json=poll_payload, timeout=30).json()
if res["errorId"] != 0:
raise RuntimeError(res["errorDescription"])
if res["status"] == "ready":
return res["solution"]["gRecaptchaResponse"]
if res["status"] == "fail":
raise RuntimeError("solve failed (refunded)")
delay = min(delay + 1, 5)
raise TimeoutError("no result in time")
print(solve_recaptcha("https://example.com/login", "6Lc_aXk..."))
Prefer plain curl over a full script? The same two calls work from the command line: POST clientKey and a task object as JSON to /createTask, then POST clientKey and the returned taskId to /getTaskResult, reading the answer back out of the solution field of the JSON response.
Tip: For other token captchas, reuse the same flow with a task type such as HCaptchaTokenTask, TurnstileTokenTask, FunCaptchaTokenTask, or GeeTestTask, and read the token from solution (solution.gRecaptchaResponse for hCaptcha, solution.token for others). Confirm the exact type string in the OMOCaptcha API docs before shipping.
Go deeper
Once your quickstart works, move on to the captcha types you actually face:
- How to solve reCAPTCHA (https://blog.omocaptcha.com/how-to-solve-recaptcha) - full v2 and v3 walkthrough.
- How to solve hCaptcha (https://blog.omocaptcha.com/how-to-solve-hcaptcha) - token flow and integration tips.
- Cloudflare Turnstile solver (https://blog.omocaptcha.com/cloudflare-turnstile-solver) - the Turnstile task in practice.
- Captcha solver API pricing (https://blog.omocaptcha.com/captcha-solver-api-pricing) - costs from $0.27 per 1000 solves.
For the official reCAPTCHA background, see Google's reCAPTCHA docs (https://developers.google.com/recaptcha/docs/display).
FAQ
How fast can I get my first captcha solve?
About five minutes: sign up, copy your clientKey, run one of the snippets above, and read solution.text. Average solve time is 0.42 seconds with up to 99% accuracy.
Why is the HTTP status always 200?
OMOCaptcha uses the standard two-step createTask/getTaskResult envelope. Transport succeeds with a 200, and the real result lives in errorId (0 = success) plus status (processing, ready, or fail). Check those fields, not the HTTP code.
What does ERROR_TASK_KEY_MISMATCH mean?
Tasks are key-bound. You must poll getTaskResult with the same clientKey that created the task. Using a different key returns ERROR_TASK_KEY_MISMATCH.
Do I pay for failed solves?
No. If status returns fail, the charge is automatically refunded to the same bucket it came from (balance, voucher balance, then package). You only pay for successful solves.
Which task type should I start with?
ImageToTextTask is the simplest because you only send a base64 image and read back solution.text. Move to token tasks like RecaptchaV2TokenTask once the loop feels familiar. Curious how OMOCaptcha compares to others? See the best captcha solving service (https://blog.omocaptcha.com/best-captcha-solving-service-2026) roundup.
Start solving now
You have everything you need to finish this captcha solver API quickstart. Sign up, claim your 1000 free solves, and run the code above against the OMOCaptcha API (https://api.omocaptcha.com/v2).
Ready to build? Get your API key on OMOCaptcha (https://omocaptcha.com/en?utm_source=blog&utm_medium=organic) and check the pricing (https://omocaptcha.com/en#pricing) starting from $0.27 per 1000 solves. Questions? Email support@omocaptcha.com any time, 24/7, and remember the full refund if your success rate ever drops below 95%. |
