API Documentation

The Image To Text API converts an image containing text into machine-readable text. This page documents how to authenticate, how to send a request, and the exact shape of every response the endpoint can return.

Base URL

All API requests use HTTPS and target the following endpoint:

POST https://www.imagetotext.me/api/image-to-text

Authentication

Every request must include your API key as a Bearer token in the Authorization header. The server validates the key against the users.api_key column and binds the request to that user’s quota.

Header:

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with the key shown in your dashboard. You can regenerate it at any time from the Profile tab.

Rate Limiting

Requests are rate-limited per API key. When the quota for the current window is exhausted the server responds with HTTP 429 Too Many Requests and the standard error envelope described below. The response may include a Retry-After header (in seconds) indicating when you can retry.

API Endpoints

Image Input Methods

The endpoint accepts the image in one of two ways — pick the one that fits your client:

Option A — multipart/form-data (file upload):
Header:
    Authorization: Bearer YOUR_API_KEY
    Content-Type: multipart/form-data
Form fields:
    file        (required) The image file to convert.

Option B — application/json (base64):
Header:
    Authorization: Bearer YOUR_API_KEY
    Content-Type: application/json
JSON body:
    {
        "base64": "data:image/png;base64,iVBORw0KG..."
    }

Request Parameters

file         (multipart/form-data) Image file. Either this OR `base64` is required.
base64       (string)              Base64-encoded image bytes. Plain base64 or a
                                   `data:;base64,...` URI is accepted.

Allowed MIME types: image/jpeg, image/png, image/gif, image/bmp, image/webp, image/tiff. The server sniffs the actual bytes — a renamed file with the wrong magic header is rejected.

Maximum size: 10 MB after decoding.

Curl Request Examples

Replace YOUR_API_KEY with your API key.

# File upload (multipart/form-data)
curl -X POST "https://www.imagetotext.me/api/image-to-text" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "file=@/path/to/image.jpg"

# JSON with base64
curl -X POST "https://www.imagetotext.me/api/image-to-text" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"base64":"data:image/png;base64,iVBORw0KG..."}'

Response Format

All responses are JSON and follow the same envelope. Clients can branch on the success flag alone.

Success Response (HTTP 200)

The data field contains the extracted text as a string:

{
    "success": true,
    "data": "extracted text from image"
}

success: always true for a 2xx response.

data: the extracted text as a string. May be empty if no text was detected — the call is still considered successful.

Error Response

Every failure uses the same shape so you only need one branch in your client:

{
    "success": false,
    "message": "Human-readable explanation."
}

Examples

# Missing input (HTTP 422)
{ "success": false, "message": "Provide either a file or a base64 image." }

# Unsupported file type (HTTP 422)
{ "success": false, "message": "Unsupported file type; allowed types are: jpg, png, gif, bmp, webp, tiff." }

# File too large (HTTP 422)
{ "success": false, "message": "The image must not exceed 10 MB." }

# Invalid / missing API key (HTTP 401)
{ "success": false, "message": "Authorization failed. Please try again." }

# Rate limit exceeded (HTTP 429)
{ "success": false, "message": "Too many requests. Please slow down." }

# Upstream OCR service failure (HTTP 502)
{ "success": false, "message": "We could not process your image right now. Please try again." }

HTTP Status Codes

200  OK                       Successful conversion.
401  Unauthorized             Missing or invalid API key.
422  Unprocessable Entity     Input validation failed
                              (no image, unsupported type, oversized, bad base64).
429  Too Many Requests        Rate limit exhausted — see Retry-After header.
502  Bad Gateway              OCR service returned an unexpected response.