Image CAPTCHA Solver API & OCR for Text Challenges

Solve image-based text CAPTCHAs in authorized QA with SolveHub's OCR API. Send a Base64 image, poll the task, and read the recognized text.

For authorized QA automation and browser integration. Use only on websites and workflows you have permission to test.

Use SolveHub's OCR API to recognize text in an image CAPTCHA on a website or workflow you are authorized to test. Send the image bytes as Base64 to POST /v1/tasks, save the returned taskId, and poll for the recognized text.

This task type is for image-based text CAPTCHAs. It is not a general solution for click-to-select puzzles, reCAPTCHA or other interactive challenges. Check current OCR availability and pricing before creating a task in live pricing.

Prepare the Image

Encode the actual image bytes as Base64 and put the string in task.base64. A data:image/...;base64, prefix is also accepted. No target URL or proxy is required for this task type.

The Base64 string must be no longer than 5,242,880 bytes, and the image must be decodable. Use the image from your authorized test; the tiny PNG in the example below is only a placeholder, not a meaningful CAPTCHA test.

The outer type and task are required; all task.* paths below are inside the task object. Field names are case-sensitive. Length limits are measured in UTF-8 bytes.

Field	Type	Required	Limit	Description
`type`	String	Yes	Must be `ocr`	Platform task type.
`task`	JSON object	Yes	≤ 7 MiB	Task parameters for this type.
`task.type`	String	No	Must be `ocr` if provided	Compatibility with the legacy request format; can be omitted in new integrations.
`task.base64`	Base64 string	Yes	≤ 5,242,880 bytes	Base64 of the raw image, optionally with a `data:image/...;base64,` prefix; content must be decodable.

Create and Poll an OCR Task

Send type ocr and the Base64 image to POST /v1/tasks. Include your API key and an Idempotency-Key. Save taskId from the create response, then request GET /v1/tasks/{taskId} about every 2–3 seconds until the task completes or fails.

{
  "type": "ocr",
  "task": {
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aK9sAAAAASUVORK5CYII="
  }
}

Replace the Key in the example with your actual value; keep the Idempotency-Key unchanged for the same business request.

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-ocr-0001' \
  --data-binary @- <<'JSON'
{
  "type": "ocr",
  "task": {
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aK9sAAAAASUVORK5CYII="
  }
}
JSON

A successful creation returns HTTP 202, and the initial status is usually queued. If the task becomes uncertain after its soft 90-second processing window, keep checking the same taskId. Do not create a replacement with a new idempotency key just because your client timed out; see retrying without duplicates and safe polling.

Read the Recognized Text

Only read solution after status is completed. For an OCR task, solution.value contains the recognized text. It may be empty or need validation in your application, so do not assume every completed response matches the expected answer.

Field	Type	How to read
`solution.value`	String	The recognized text; the actual value may be empty or may need further validation on your side.

Sample result: {"value":"EXTRACTED_TEXT"}.

Troubleshoot OCR Requests

A Base64 value that is too large, invalid or not a decodable image returns 400 INVALID_TASK. If creation returns 402, check your balance; for 429, respect the rate limit; for 503, check whether OCR is currently available. Use the API error and X-Request-ID when investigating a failed request.

Common errors on create requests are 400 INVALID_TASK, 402 INSUFFICIENT_BALANCE, 429 TASK_LIMIT_EXCEEDED, and 503 TYPE_UNAVAILABLE. When a created task fails, the public error code is TASK_FAILED or TASK_TIMEOUT; uncertain corresponds to TASK_UNCERTAIN.

The processing window starts after task creation is confirmed; queue waiting does not consume it.

Next Steps

Read the quick start for authentication and polling, the pricing page for live OCR availability, and the Platform API reference for full response and error fields.

Image CAPTCHA Solver API: OCR for Text Challenges