API Reference

Authentication

All API requests require a Bearer API key in the Authorization header. Generate keys from your dashboard.

# All authenticated requests require this header:
Authorization: Bearer sk-ocr-your-api-key

# Example:
curl -X POST https://api.open-ocr.com/v1/ocr \
  -H "Authorization: Bearer sk-ocr-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "engine": "mistral-mistral-ocr-4-1", "input": { "type": "url", "url": "https://example.com/doc.png" } }'

Request Parameters — POST /v1/ocr

Response Fields

Examples

curl -X POST https://api.open-ocr.com/v1/ocr \
  -H "Authorization: Bearer sk-ocr-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req-$(uuidgen)" \
  -d '{
    "engine": "mistral-mistral-ocr-4-1",
    "input": {
      "type": "url",
      "url": "https://example.com/invoice.png"
    }
  }'

# 200 OK (status: "succeeded"; still read the status field, not only the HTTP code)
{
  "request_id": "req_abc123",
  "status": "succeeded",
  "engine": "mistral-mistral-ocr-4-1",
  "extracted_text": "Invoice #1042\nDate: 2026-02-28\nTotal: $42.00",
  "extracted_text_preview": "Invoice #1042...",
  "pages": 1,
  "cost_debited": 0.005,
  "provider_latency_ms": 148,
  "confidence": 0.94
}

curl -X POST https://api.open-ocr.com/v1/ocr \
  -H "Authorization: Bearer sk-ocr-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req-$(uuidgen)" \
  -d '{
    "engine": "mistral-mistral-ocr-4-1",
    "page_count": 3,
    "input": {
      "type": "url",
      "url": "https://example.com/report.pdf"
    }
  }'

# 200 OK (status: "succeeded"; still read the status field, not only the HTTP code)
{
  "request_id": "req_pdf456",
  "status": "succeeded",
  "engine": "mistral-mistral-ocr-4-1",
  "extracted_text": "Page 1 content...\n--- Page 2 ---\nPage 2 content...\n--- Page 3 ---\nPage 3 content...",
  "pages": 3,
  "cost_debited": 0.015,
  "provider_latency_ms": 820
}

# Omit page_count and only page 1 is processed. pages_total and warnings tell you.
# 200 OK (status: "succeeded"; still read the status field, not only the HTTP code)
{
  "request_id": "req_pdf457",
  "status": "succeeded",
  "engine": "mistral-mistral-ocr-4-1",
  "extracted_text": "Page 1 content...",
  "pages": 1,
  "pages_total": 3,
  "warnings": ["document has 3 pages; processed 1. Set page_count to process more."],
  "cost_debited": 0.005
}

curl -X POST https://api.open-ocr.com/v1/ocr \
  -H "Authorization: Bearer sk-ocr-your-api-key" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "local-tesseract",
    "input": {
      "type": "url",
      "url": "https://example.com/japanese-receipt.png"
    },
    "settings": {
      "language": "ja"
    }
  }'

# 200 OK (status: "succeeded"; still read the status field, not only the HTTP code)
{
  "request_id": "req_ja789",
  "status": "succeeded",
  "engine": "local-tesseract",
  "extracted_text": "領収書\n合計: ¥4,200",
  "pages": 1,
  "cost_debited": 0.002,
  "provider_latency_ms": 1420,
  "applied_settings": { "language": "ja" }
}

# Encode image locally
IMAGE_B64=$(base64 -w 0 /path/to/receipt.png)

curl -X POST https://api.open-ocr.com/v1/ocr \
  -H "Authorization: Bearer sk-ocr-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req-$(uuidgen)" \
  -d "{
    \"engine\": \"mistral-mistral-ocr-4-1\",
    \"input\": {
      \"type\": \"base64\",
      \"data_base64\": \"$IMAGE_B64\",
      \"mime_type\": \"image/png\"
    }
  }"

# 200 OK (status: "succeeded") — same response shape as URL input

Text and markdown output

With output_format set to text or markdown the body is text rather than JSON (for markdown, a fixed wrapper followed by the unchanged engine output, shown below), so page information travels in response headers (all exposed to browsers via CORS):

# OCR Result

**Engine:** mistral-mistral-ocr-4-1
**Status:** succeeded

---

<engine output, exactly as the engine returned it>

Large PDF jobs may add a pages_failed array to the finished result, together with a warning such as "page 4 failed OCR". On an async 202, pages_total is known for base64 inputs only; for URL inputs it appears when you poll or receive the webhook. Text conversion rules are listed below. Batch items carry pages, pages_total and warnings. GET /v1/ocr/{request_id} returns them once the request has finished, including on replays. Text output text is plain text with markdown stripped; markdown returns a fixed header followed by the engine output, which is not modified:

HTTP status codes for OCR requests

• A completed, successful synchronous request with the default JSON output returns 200 with status: "succeeded" in the body. Still check the status field, not only the HTTP code: a response can also carry partial, refunded or another non-success status. When a slow response was committed early (headers flushed before the result), a completed success is HTTP 202 with status: "succeeded" and http_status: 200 in the body, so do not treat every 202 as still running.
• With output_format text or markdown, a completed request returns 200.
• An async submit returns 202 with status: "processing" and a poll_url.
• A replay (same Idempotency-Key with the same request) returns the stored OUTCOME (the status field) with that outcome's normal HTTP code, which is not always the code first seen: a slow first response may have arrived as an early-flushed 202 carrying http_status, and its replay is then 200 for a success. The normal codes are: a success 200, a refunded request 202 with status: "refunded", and a timeout 503 with status: "timeout", a Retry-After header and retry_after_seconds in the body. Replaying an in-flight async request returns 202 JSON with the poll_url. This is about POST replays. GET /v1/ocr/{request_id} is separate: it returns 200 for a finished request only while OCR history is retained, and 410 result_not_retained otherwise; refunded and timeout outcomes read as failed there.

Plain-text conversion rules

output_format: "text" converts the engine output like this. With the default JSON format, extracted_text stays the raw engine output and extracted_text_plain carries this conversion when it differs.

• Tables: markdown tables (pipe rows with a separator row of 3 or more dashes) become tab-separated rows. Separator rows are dropped and <br> inside a cell becomes a space. Pipe lines without a separator row are left as they are.
• Code fences: the fence lines are dropped and the content is kept verbatim.
• Headings: the # to ###### markers are removed, and closing #s only when preceded by whitespace (# C# becomes C#).
• Horizontal rules: a line whose content (ignoring surrounding spaces) is exactly --- is kept, because PDF pages are joined with a blank line, ---, and a blank line, so it marks page breaks (use pages and pages_total for the authoritative page count). ***, ___, - - -, * * * and _ _ _ are dropped.
• Bullets: lines starting with "* " become "- ".
• Emphasis: ***, **, * and ~~ are stripped using flanking rules, so 5 * 3 and 2*3*4 survive. Underscores are not treated as emphasis.
• Inline code: the backtick delimiters (matched by equal run length) are removed and the content is kept literal, so emphasis and images inside code are not touched.
• Images: ![alt](url) is removed entirely.
• Escapes: \*, \_, \|, \# and \` become the literal character.
• Everything else is unchanged: links [text](url), underscores and bare URLs stay as they are. Text that is already plain is returned byte-identical.

GET /v1/ocr/{request_id} — Poll for a result

An async request (mode: "async") returns status: "processing" and a request_id. Poll this endpoint with that ID until status is no longer queued or processing. GET returns these statuses: queued and processing (still running), then succeeded, partial (some text recovered), failed or rejected. GET never returns refunded or timeout: the router stores those outcomes as failed (read provider_error). Those two words appear only in the original POST response. For a partial result the full text is not stored: read extracted_text_preview (up to 2,000 characters) and warning. Or set webhook_url to be called instead. The same endpoint recovers the saved result of a synchronous request whose connection dropped. Polling only reads the saved request: it does not run OCR again and is not charged. It takes no Idempotency-Key.

curl https://api.open-ocr.com/v1/ocr/req_abc123 \
  -H "Authorization: Bearer sk-ocr-your-api-key"

# Still running: read the "status" field, not the HTTP code
# { "request_id": "req_abc123", "status": "processing" }

# Partial (some text recovered): extracted_text is null; only the preview is stored
# { "request_id": "req_abc123", "status": "partial", "extracted_text": null,
#   "extracted_text_preview": "First 2,000 characters...", "warning": "..." }

# Completed: 200 OK (a replay of a finished request)
# {
#   "request_id": "req_abc123",
#   "status": "succeeded",
#   "engine": "mistral-mistral-ocr-4-1",
#   "extracted_text": "Invoice #1042...",
#   "pages": 1,
#   "cost_debited": 0.005
# }

Poll every few seconds and stop on a terminal status. If OCR history is turned off for your account the saved text is not retained; see recovering results. The charge for a request is the cost_debited value in the original POST response (and cost_usd in the webhook). This GET repeats it only while OCR history is enabled: with history off it returns 410 result_not_retained.

Error Codes

All errors return a consistent JSON envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "Idempotency-Key header is required"
  }
}

The machine-readable field is error.code(not type). Errors do not always include a request_id.

{ "error": { "code": "invalid_request", "message": "Idempotency-Key header is required" } }

{ "error": { "code": "unknown_engine", "message": "'mistral-ocr-4-1' is not a known engine id. Did you mean: mistral-mistral-ocr-4-1?", "suggestions": ["mistral-mistral-ocr-4-1"] } }

{ "error": { "code": "authentication_error", "message": "Invalid API key" } }

{ "error": { "code": "insufficient_balance", "message": "Insufficient balance to process any pages. Need $0.005, have $0.0001" } }

{ "error": { "code": "insufficient_scope", "message": "This API key does not have access to this resource" } }

{ "error": { "code": "payload_too_large", "message": "Request body exceeds 10 MB limit" } }

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded" }, "retry_after_seconds": 30 }

{ "error": { "code": "internal_error", "message": "An unexpected error occurred" } }

{ "error": { "code": "provider_error", "message": "Engine returned a non-200 status" } }

{ "error": { "code": "engine_unavailable", "message": "Engine local-easyocr is currently unavailable" } }

For retry strategies per error code, see the Error Codes page.

Billing on Failed Requests

A failure is not automatically free. What you pay depends on whether the engine actually ran.

• The engine never ran — invalid input, authentication, rate limits, an unavailable or misconfigured engine, or any failure on our side. You are not charged, and any provisional debit is refunded.
• The engine ran and then failed — it errored partway, timed out mid-generation, or returned unusable output. You are charged the provider's cost for that attempt, passed through at cost including provider fees. The initial estimate is not a billing cap. Every customer-authorized retry is billable.
• Unknown cost stays pending. We charge only verified amounts. A provider charge confirmed after the response will be debited later, once. The charge is the cost_debited value in the original POST response (and cost_usd in the webhook); GET /v1/ocr/{request_id} repeats it only when OCR history is enabled.

On the wire this means cost_debited may be non-zero on a response whose status is "failed". A charged failure does not get a status or error code of its own — cost_debited is where you read the charge, and provider_error tells you what went wrong. Successful requests are unaffected and bill at the published price.

{
  "request_id": "req_abc123",
  "status": "failed",
  "engine": "google-gemini-3.1-flash-lite",
  "extracted_text": null,
  "pages": 0,
  "cost_debited": 0.0004,
  "provider_error": "Engine timed out after generating a partial response"
}

Here the engine was quoted at $0.0006 for the page and the provider billed us $0.0004 for the tokens their model produced before it failed, so $0.0004 is what you pay.

Full policy, including a worked example, on the Error Codes page.

Rate Limits

All authenticated endpoints are limited to 60 requests per minute per API key. Every response includes rate-limit headers.

# Headers on every response:
X-RateLimit-Limit: 60          # requests allowed per window
X-RateLimit-Remaining: 42      # requests left
X-RateLimit-Reset: 1709251200  # Unix timestamp when window resets

# On 429:
Retry-After: 18                # seconds to wait

import time, uuid, requests

def ocr_with_retry(payload, api_key, max_retries=3):
    idempotency_key = str(uuid.uuid4())  # one key per logical request, reused on every retry
    for attempt in range(max_retries + 1):
        resp = requests.post(
            "https://api.open-ocr.com/v1/ocr",
            json=payload,
            headers={
                "Authorization": f"Bearer {api_key}",
                "Idempotency-Key": idempotency_key,
            },
            timeout=(5, 240),  # connect 5s, read 240s: above the router's 215s max wall
        )
        if resp.status_code != 429:
            return resp
        wait = float(resp.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait)
    return resp

payload = {"engine": "mistral-mistral-ocr-4-1", "input": {"type": "url", "url": "https://example.com/doc.png"}}
api_key = "sk-ocr-your-api-key"
resp = ocr_with_retry(payload, api_key)

# Use it: HTTP 2xx only means the call completed. Check the body status.
body = resp.json()
if body.get("status") == "timeout":
    # A timed-out request replays as the same 503 for this key, forever. Report it, or start a
    # NEW attempt with a NEW Idempotency-Key. Never loop on the same key.
    raise RuntimeError("OCR timed out; retry with a NEW Idempotency-Key")
if not resp.ok:
    # Error envelope: {"error": {"code", "message"}} with no "status" field, for example
    # 409 idempotency_key_reused (the key was used with a different request).
    err = body.get("error", {})
    raise RuntimeError(f"HTTP {resp.status_code} {err.get('code')}: {err.get('message')}")
if body["status"] != "succeeded":
    raise RuntimeError(f"OCR ended as {body['status']}: {body.get('provider_error')}")
print(body["extracted_text"])

API Key Guide

# Store your API key as an environment variable
export OPENOCR_API_KEY="sk-ocr-your-api-key"

# Reference it in curl
curl -X POST https://api.open-ocr.com/v1/ocr \
  -H "Authorization: Bearer $OPENOCR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"engine":"mistral-mistral-ocr-4-1","input":{"type":"url","url":"https://example.com/doc.png"}}'

import os
import uuid

import requests

response = requests.post(
    "https://api.open-ocr.com/v1/ocr",
    headers={
        "Authorization": f"Bearer {os.environ['OPENOCR_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "engine": "mistral-mistral-ocr-4-1",
        "input": {"type": "url", "url": "https://example.com/doc.png"},
    },
)
response.raise_for_status()
body = response.json()
assert body["status"] == "succeeded", body
print(body["extracted_text"])

// Node.js 18+: load the key from the environment
const response = await fetch("https://api.open-ocr.com/v1/ocr", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENOCR_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    engine: "mistral-mistral-ocr-4-1",
    input: { type: "url", url: "https://example.com/doc.png" },
  }),
});
const result = await response.json();
if (result.status !== "succeeded") throw new Error("OCR ended as " + (result.status ?? result.error?.code)); // error envelopes have no status
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);
console.log(result.extracted_text);

Official OpenOCR SDKs are coming soon; these examples call the REST API directly.

GET /v1/engines

List all available OCR engines. No request body required.

curl https://api.open-ocr.com/v1/engines \
  -H "Authorization: Bearer $OPENOCR_API_KEY"

# 200 OK — array of engine objects
# [
#   {
#     "id": "mistral-mistral-ocr-4-1",
#     "name": "Mistral OCR 4.1",
#     "provider": "mistral",
#     "capabilities": ["printed", "handwritten", "pdf"],
#     "price_per_page": 0.005
#   },
#   ...
# ]

File Upload Constraints

# Upload a local file via base64
IMG_B64=$(base64 -w 0 /path/to/invoice.png)

curl -X POST https://api.open-ocr.com/v1/ocr \
  -H "Authorization: Bearer $OPENOCR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{
    \"engine\": \"mistral-mistral-ocr-4-1\",
    \"input\": {
      \"type\": \"base64\",
      \"data_base64\": \"$IMG_B64\",
      \"mime_type\": \"image/png\"
    }
  }"

import base64, requests, os, uuid

with open("invoice.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.open-ocr.com/v1/ocr",
    headers={
        "Authorization": f"Bearer {os.environ['OPENOCR_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "engine": "mistral-mistral-ocr-4-1",
        "input": {"type": "base64", "data_base64": b64, "mime_type": "image/png"},
    },
    timeout=60,
)
resp.raise_for_status()  # an error envelope has no "status" field
body = resp.json()
assert body["status"] == "succeeded", body
print(body["extracted_text"])