OCR Image to Text API

Convert an image to text with the Solverify OCR Image to Text API. Submit a Base64-encoded image as an ocr task, then retrieve the recognized characters from solution.value when processing completes.

Use this API for image-based text challenges and supported OCR workflows that need a simple asynchronous create-and-poll integration.

OCR follows the standard Solverify task workflow:

1. Encode the image as Base64.
2. Create an ocr task with POST /createTask.
3. Store the returned taskId.
4. Poll POST /getTaskResult until the task is completed.
5. Read the extracted text from solution.value.

Request Parameters

The base64 value can contain raw Base64 or an image data URI such as data:image/png;base64,.... Whitespace in the encoded value is removed before the image is decoded.

Create OCR Task Request

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ocr",
    "base64": "BASE64_ENCODED_IMAGE"
  }
}

Create Task Response

A successful request returns the task identifier used to retrieve the OCR result:

{
  "errorId": 0,
  "taskId": "UUID"
}

Completed OCR Result

When processing completes, solution.value contains the extracted text:

{
  "errorId": 0,
  "status": "completed",
  "solution": {
    "value": "EXTRACTED_TEXT"
  },
  "errorCode": null,
  "errorDescription": null
}

OCR Image to Text Code Examples

The following examples encode a local image, create an OCR task, and poll for the extracted text. Replace captcha.png with your image path.

# Requires jq for JSON construction and response parsing.
IMAGE_BASE64=$(base64 < captcha.png | tr -d '\n')

CREATED=$(curl --fail --silent --show-error \
  --request POST \
  --url https://solver.solverify.net/createTask \
  --header "Content-Type: application/json" \
  --data "$(jq -n \
    --arg key "$SOLVERIFY_API_KEY" \
    --arg image "$IMAGE_BASE64" \
    '{clientKey: $key, task: {type: "ocr", base64: $image}}')")

if [ "$(printf '%s' "$CREATED" | jq -r '.errorId')" != "0" ]; then
  printf '%s\n' "$CREATED" >&2
  exit 1
fi

TASK_ID=$(printf '%s' "$CREATED" | jq -r '.taskId')

while true; do
  RESULT=$(curl --fail --silent --show-error \
    --request POST \
    --url https://solver.solverify.net/getTaskResult \
    --header "Content-Type: application/json" \
    --data "$(jq -n \
      --arg key "$SOLVERIFY_API_KEY" \
      --arg taskId "$TASK_ID" \
      '{clientKey: $key, taskId: $taskId}')")

  if [ "$(printf '%s' "$RESULT" | jq -r '.errorId')" != "0" ]; then
    printf '%s\n' "$RESULT" >&2
    exit 1
  fi

  if [ "$(printf '%s' "$RESULT" | jq -r '.status')" = "completed" ]; then
    printf '%s' "$RESULT" | jq -r '.solution.value'
    break
  fi

  sleep 2
done

OCR Timeout

OCR tasks can run for up to approximately 30 seconds before timing out internally. Your application should use its own overall polling deadline and stop when the API returns an error.

Image Preparation Recommendations

For clearer OCR results:

• Crop the image to the text region when possible.
• Use an image with readable characters and strong foreground-to-background contrast.
• Avoid unnecessary scaling or compression that makes characters difficult to distinguish.
• Remove line breaks from Base64 when constructing JSON manually, although the solver also strips whitespace.
• Check the encoded string length before submission to stay within the 5,242,880-character limit.

OCR API Errors

OCR requests can return standard Solverify errors such as:

For recovery guidance and every supported error, see Solverify API Error Codes.

Next Steps

After creating an OCR task, poll the Get Task Result API with the returned taskId. Poll every 2 to 3 seconds and stop when the task completes or returns an error.

Frequently Asked Questions

What does the OCR Image to Text API return?

A completed OCR task returns the recognized text in solution.value.

Does OCR require a proxy or website URL?

No. OCR tasks only require clientKey, task.type, and the Base64 image content.

Can I send an image data URI?

Yes. The OCR solver accepts raw Base64 and values beginning with an image data URI prefix such as data:image/png;base64,.

What is the maximum OCR image size?

The base64 request field can contain up to 5,242,880 characters. This limit applies to the encoded string, not the original image file size.

Why did the OCR task return no text?

The image may not contain supported characters with sufficient clarity. Try cropping the text region and improving contrast or image quality before submitting another task.