API Overview
Shared concepts across all Developer API endpoints — error codes, rate limits, billing, idempotency, and input formats.
Base URL
https://image-to-text.org/api/v1All endpoints are synchronous — results are returned in the same HTTP response.
Authentication
Every request must include an API key. See Getting Started for setup.
Authorization: Bearer YOUR_API_KEYor:
x-api-key: YOUR_API_KEYRequests without a valid key receive 401 Unauthorized. Keys must have the correct scope for the endpoint (e.g., ocr scope for OCR endpoints, image scope for image processing endpoints).
Request ID
Every response includes a request_id — a unique identifier for that request. Include it when contacting support. It also appears in your API request logs for billing and debugging.
Error Codes
All errors follow a consistent contract:
| Status | Code | Retryable | Meaning |
|---|---|---|---|
| 401 | unauthorized | No | Missing, invalid, or disabled API key |
| 402 | credits_insufficient | No | Not enough processing credits |
| 400 | file_error | No | No input, multiple inputs, or invalid input format |
| 409 | idempotency_conflict | No | Reused idempotency key with different input |
| 413 | limit_exceeded | No | File too large or too many pages |
| 415 | invalid_input | No | Unsupported image format |
| 422 | empty_result | No | No readable text found in the file |
| 429 | rate_limited | Yes | Too many requests — retry after the specified seconds |
| 429 | limit_exceeded | No | Daily request limit reached |
| 500 | config_error | No | Service not configured |
| 502 | network_error | Yes | Unable to reach the processing provider |
| 504 | upstream_timeout | Yes | Provider timed out — retry |
Retryable errors are safe to retry. Use exponential backoff (start at 1s, double each retry, max 3 retries).
Rate Limits
Per-key rate limits apply separately to OCR and Image Processing scopes:
- Minimum interval between requests (configurable, default ~5s)
- Daily request limit — separate limits for free and paid-tier users
When rate-limited, the response includes a Retry-After header with the seconds to wait.
Billing
Requests are billed in Processing Credits:
| Endpoint | Cost Basis |
|---|---|
| OCR (Simple mode) | 1 credit per page |
| OCR (Formatted mode) | 10 credits per page |
| Image Convert | Based on pixel workload |
| Image Compress | Based on pixel workload |
Credits are deducted only after successful processing. Failed requests are not charged.
Idempotency
For billable endpoints, include an Idempotency-Key header to prevent duplicate charges on retry:
Idempotency-Key: <alphanumeric string, max 191 chars>- Keys are scoped to your API key and valid for 24 hours
- Same key + same input → returns the cached result without charging again
- Same key + different input →
409 idempotency_conflicterror - Recommended format:
{operation}-{timestamp}-{unique_suffix}
Input Formats
OCR
| Format | File Extension | Notes |
|---|---|---|
| JPEG | .jpg, .jpeg | |
| PNG | .png | |
| GIF | .gif | |
| WebP | .webp | |
| BMP | .bmp | |
| TIFF | .tif, .tiff | Single-image only |
.pdf | Up to 20MB |
Image Processing
Input formats: JPEG, PNG, WebP, AVIF, GIF, TIFF (static)
Output formats: JPEG, PNG, WebP, AVIF
Multiple Input Sources
Every endpoint accepts three ways to provide your source file:
| Source | Content-Type | Field |
|---|---|---|
| File upload | multipart/form-data | file |
| Public URL | multipart/form-data or application/json | image_url |
| Base64 | multipart/form-data or application/json | base64 + mime_type |
Remote URLs must be publicly accessible. Private, local, link-local, and cloud metadata addresses are blocked.