OCR API
turn images and PDFs into Markdown, plain text, and page-level layout JSON from your own product workflow.
Endpoint: POST /api/v1/ocr
Recognize documents with one endpoint
Authenticate with a server-side Developer API Key that has the OCR scope, submit exactly one file, public image URL, or Base64 payload, and receive normalized OCR output. Successful calls consume Processing Credits after recognition and every valid-key call is logged for usage reporting.
POST https://your-domain.com/api/v1/ocr
Authorization: Bearer YOUR_API_KEY
OpenAPI: GET /api/v1/openapicurl file upload
curl -X POST https://your-domain.com/api/v1/ocr \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: invoice-001" \
-F "[email protected]" \
-F "mode=formatted"JavaScript image URL
// Run this from your backend, not browser JavaScript.
const res = await fetch('https://your-domain.com/api/v1/ocr', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.DEVELOPER_API_KEY}`,
'Idempotency-Key': 'scan-001',
'Content-Type': 'application/json'
},
body: JSON.stringify({
image_url: 'https://example.com/scan.png',
mode: 'simple'
})
});
const data = await res.json();Python Base64
import base64
import requests
with open('receipt.jpg', 'rb') as f:
encoded = base64.b64encode(f.read()).decode('utf-8')
res = requests.post(
'https://your-domain.com/api/v1/ocr',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={
'base64': encoded,
'mime_type': 'image/jpeg',
'file_name': 'receipt.jpg',
'mode': 'formatted'
},
timeout=120,
)
print(res.json())Request fields
Response contract
Returns success, request_id, elapsed_ms, markdown, text, pages, and usage.
The API key is missing, invalid, or disabled.
The key owner does not have enough Processing Credits for the estimated page count and OCR mode.
The Idempotency-Key was already used with different OCR input.
The input was processed, but no readable text was found.
The key hit the daily OCR API limit, page limit, or minimum request interval.
Built for product integrations
The API uses the same OCR normalization, Processing Credit rules, and limits as the web product.
Developer API Key authentication
Users can create Developer API Keys with the OCR scope. The full secret is shown only once and should stay on your server.
Processing Credit metering
Simple and formatted recognition consume Processing Credits by page after successful OCR.
Usage logs
Valid-key requests are recorded with request_id, status, latency, Processing Credits, source type, IP, and user agent.
Data handling boundary
API logs keep metering metadata for monitoring and abuse detection. OCR output is returned to the caller, and failed recognition is not charged.
OCR API FAQ
Authentication, billing, and response details for developers.
Start integrating OCR
Create a Developer API Key, send a test request, and monitor usage from your API key list.